javax.obex
Interface Operation

All Superinterfaces:
Connection, ContentConnection, InputConnection, OutputConnection, StreamConnection

public interface Operation
extends ContentConnection

The Operation 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 IOException is thrown on the next read from the input stream, write to the output stream, or call to sendHeaders().

Definition of methods inherited from ContentConnection

getEncoding() will always return null.
getLength() will return the length specified by the OBEX Length header or -1 if the OBEX Length header was not included.
getType() will return the value specified in the OBEX Type header or null if the OBEX Type header was not included.

How Headers are Handled

As headers are received, they may be retrieved through the getReceivedHeaders() method. If new headers are set during the operation, the new headers will be sent during the next packet exchange.

PUT example

 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();
 }
 

GET example

 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;
 }
 

Client PUT Operation Flow

For PUT operations, a call to close() the OutputStream returned from openOutputStream() or openDataOutputStream() 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 getResponseCode() will do an implicit close on the OutputStream and therefore signal that the request is done.

Client GET Operation Flow

For GET operation, a call to openInputStream() or openDataInputStream() will signal that the request is done. (In OBEX terms, the final bit in the request will be set.) A call to getResponseCode() will cause an implicit close on the InputStream. No further data may be read at this point.

Since:
BlackBerry API 4.2.1

Method Summary
 void abort()
          Sends an ABORT message to the server.
 HeaderSet getReceivedHeaders()
          Returns the headers that have been received during the operation.
 int getResponseCode()
          Returns the response code received from the server.
 void sendHeaders(HeaderSet headers)
          Specifies the headers that should be sent in the next OBEX message that is sent.
 
Methods inherited from interface javax.microedition.io.ContentConnection
getEncoding, getLength, getType
 
Methods inherited from interface javax.microedition.io.InputConnection
openDataInputStream, openInputStream
 
Methods inherited from interface javax.microedition.io.Connection
close
 
Methods inherited from interface javax.microedition.io.OutputConnection
openDataOutputStream, openOutputStream
 
Methods inherited from interface javax.microedition.io.Connection
close
 



Method Detail

abort

void abort()
           throws IOException
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 close() will be called by this method.

Throws:
IOException - if the transaction has already ended or if an OBEX server calls this method
Since:
BlackBerry API 4.2.1

getReceivedHeaders

HeaderSet getReceivedHeaders()
                             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.

Returns:
the headers received during this Operation
Throws:
IOException - if this Operation has been closed
Since:
BlackBerry API 4.2.1

sendHeaders

void sendHeaders(HeaderSet headers)
                 throws IOException
Specifies the headers that should be sent in the next OBEX message that is sent.

Parameters:
headers - the headers to send in the next message
Throws:
IOException - if this Operation has been closed or the transaction has ended and no further messages will be exchanged
IllegalArgumentException - if headers was not created by a call to ServerRequestHandler.createHeaderSet() or ClientSession.createHeaderSet()
NullPointerException - if headers if null
Since:
BlackBerry API 4.2.1

getResponseCode

int getResponseCode()
                    throws IOException
Returns the response code received from the server. Response codes are defined in the ResponseCodes class.

Returns:
the response code retrieved from the server
Throws:
IOException - if an error occurred in the transport layer during the transaction; if this object was created by an OBEX server
See Also:
ResponseCodes
Since:
BlackBerry API 4.2.1





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.