1 files changed, 200 insertions, 0 deletions
diff --git a/obex/javax/obex/Operation.java b/obex/javax/obex/Operation.java
new file mode 100644
index 0000000..120852a
--- /dev/null
+++ b/obex/javax/obex/Operation.java
@@ -0,0 +1,200 @@
+/*
+ * Copyright (c) 2008-2009, Motorola, Inc.
+ *
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * - Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * - Redistributions in binary form must reproduce the above copyright notice,
+ * this list of conditions and the following disclaimer in the documentation
+ * and/or other materials provided with the distribution.
+ *
+ * - Neither the name of the Motorola, Inc. nor the names of its contributors
+ * may be used to endorse or promote products derived from this software
+ * without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+ * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+ * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+ * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ */
+
+package javax.obex;
+
+import java.io.DataInputStream;
+import java.io.DataOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.io.OutputStream;
+
+/**
+ * The <code>Operation</code> interface provides ways to manipulate a single
+ * OBEX PUT or GET operation.  The implementation of this interface sends
+ * OBEX packets as they are built.  If during the operation the peer in the
+ * operation ends the operation, an <code>IOException</code> is thrown on
+ * the next read from the input stream, write to the output stream, or call to
+ * <code>sendHeaders()</code>.
+ * <P>
+ * <STRONG>Definition of methods inherited from <code>ContentConnection</code></STRONG>
+ * <P>
+ * <code>getEncoding()</code> will always return <code>null</code>.
+ * <BR><code>getLength()</code> will return the length specified by the OBEX Length
+ * header or -1 if the OBEX Length header was not included.
+ * <BR><code>getType()</code> will return the value specified in the OBEX Type
+ * header or <code>null</code> if the OBEX Type header was not included.<BR>
+ * <P>
+ * <STRONG>How Headers are Handled</STRONG>
+ * <P>
+ * As headers are received, they may be retrieved through the
+ * <code>getReceivedHeaders()</code> method.  If new headers are set during the
+ * operation, the new headers will be sent during the next packet exchange.
+ * <P>
+ * <STRONG>PUT example</STRONG>
+ * <P>
+ * <PRE>
+ * void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj)
+ *     throws IOException {
+ *
+ *     // Include the length header
+ *     head.setHeader(head.LENGTH, new Long(obj.length));
+ *
+ *     // Initiate the PUT request
+ *     Operation op = conn.put(head);
+ *
+ *     // Open the output stream to put the object to it
+ *     DataOutputStream out = op.openDataOutputStream();
+ *
+ *     // Send the object to the server
+ *     out.write(obj);
+ *
+ *     // End the transaction
+ *     out.close();
+ *     op.close();
+ * }
+ * </PRE>
+ * <P>
+ * <STRONG>GET example</STRONG>
+ * <P>
+ * <PRE>
+ * byte[] getObjectViaOBEX(ClientSession conn, HeaderSet head) throws IOException {
+ *
+ *     // Send the initial GET request to the server
+ *     Operation op = conn.get(head);
+ *
+ *     // Retrieve the length of the object being sent back
+ *     int length = op.getLength();
+ *
+ *      // Create space for the object
+ *      byte[] obj = new byte[length];
+ *
+ *     // Get the object from the input stream
+ *     DataInputStream in = trans.openDataInputStream();
+ *     in.read(obj);
+ *
+ *     // End the transaction
+ *     in.close();
+ *     op.close();
+ *
+ *     return obj;
+ * }
+ * </PRE>
+ * <H3>Client PUT Operation Flow</H3>
+ * For PUT operations, a call to <code>close()</code> the <code>OutputStream</code>
+ * returned from <code>openOutputStream()</code> or <code>openDataOutputStream()</code>
+ * will signal that the request is done.  (In OBEX terms, the End-Of-Body header should
+ * be sent and the final bit in the request will be set.)  At this point, the
+ * reply from the server may begin to be processed.  A call to
+ * <code>getResponseCode()</code> will do an implicit close on the
+ * <code>OutputStream</code> and therefore signal that the request is done.
+ * <H3>Client GET Operation Flow</H3>
+ * For GET operation, a call to <code>openInputStream()</code> or
+ * <code>openDataInputStream()</code> will signal that the request is done.  (In OBEX
+ * terms, the final bit in the request will be set.)  A call to
+ * <code>getResponseCode()</code> will cause an implicit close on the
+ * <code>InputStream</code>.  No further data may be read at this point.
+ *
+ * @version 0.3 November 28, 2008
+ */
+public interface Operation {
+
+    /**
+     * Sends an ABORT message to the server.  By calling this method, the
+     * corresponding input and output streams will be closed along with this
+     * object.  No headers are sent in the abort request.  This will end the
+     * operation since <code>close()</code> will be called by this method.
+     *
+     * @exception IOException if the transaction has already ended or if an
+     * OBEX server calls this method
+     */
+    public void abort() throws IOException;
+
+    /**
+     * Returns the headers that have been received during the operation.
+     * Modifying the object returned has no effect on the headers that are
+     * sent or retrieved.
+     *
+     * @return the headers received during this <code>Operation</code>
+     *
+     * @exception IOException if this <code>Operation</code> has been closed
+     */
+    public HeaderSet getReceivedHeaders() throws IOException;
+
+    /**
+     * Specifies the headers that should be sent in the next OBEX message that
+     * is sent.
+     *
+     * @param headers the headers to send in the next message
+     *
+     * @exception IOException  if this <code>Operation</code> has been closed
+     * or the transaction has ended and no further messages will be exchanged
+     *
+     * @exception IllegalArgumentException if <code>headers</code> was not created
+     * by a call to <code>ServerRequestHandler.createHeaderSet()</code> or
+     * <code>ClientSession.createHeaderSet()</code>
+     *
+     * @exception NullPointerException if <code>headers</code> if <code>null</code>
+     */
+    public void sendHeaders(HeaderSet headers) throws IOException;
+
+    /**
+     * Returns the response code received from the server.  Response codes
+     * are defined in the <code>ResponseCodes</code> class.
+     *
+     * @see ResponseCodes
+     *
+     * @return the response code retrieved from the server
+     *
+     * @exception IOException if an error occurred in the transport layer during
+     * the transaction; if this object was created by an OBEX server
+     */
+    public int getResponseCode() throws IOException;
+
+    public String getEncoding();
+
+    public long getLength();
+
+    public String getType();
+
+    public InputStream openInputStream() throws IOException;
+
+    public DataInputStream openDataInputStream() throws IOException;
+
+    public OutputStream openOutputStream() throws IOException;
+
+    public DataOutputStream openDataOutputStream() throws IOException;
+
+    public void close() throws IOException;
+
+    public int getMaxPacketSize();
+}