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