javax.obex
Interface ClientSession

All Superinterfaces:
Connection

public interface ClientSession
extends Connection

The ClientSession interface provides methods for OBEX requests. This interface provides a way to define headers for any OBEX operation. OBEX operations are CONNECT, SETPATH, PUT, GET and DISCONNECT. For PUTs and GETs, this interface will return a javax.obex.Operation object to complete the operations. For CONNECT, DISCONNECT, and SETPATH operations, this interface will complete the operation and return the result in a HeaderSet object.

Connection ID and Target Headers

According to the IrOBEX specification, a packet may not contain a Connection ID and Target header. Since the Connection ID header is managed by the implementation, it will not send a Connection ID header if a Connection ID was specified in a packet that has a Target header. In other words, if an application adds a Target header to a HeaderSet object used in an OBEX operation and a Connection ID was specified, no Connection ID will be sent in the packet containing the Target header.

CREATE-EMPTY and PUT-DELETE Requests

To perform a CREATE-EMPTY request, the client must call the put() method. With the Operation object returned, the client must open the output stream by calling openOutputStream() and then close the stream by calling close() on the OutputStream without writing any data. Using the DataOutputStream returned from openDataOutputStream() works the same way.

There are two ways to perform a PUT-DELETE request. The delete() method is one way to perform a PUT-DELETE request. The second way to perform a PUT-DELETE request is by calling put() and never calling openOutputStream() or openDataOutputStream() on the Operation object returned from put().

PUT example

 void putObjectViaOBEX(ClientSession conn, HeaderSet head, byte[] obj)
     throws IOException {

     // Include the length header
     head.setHeader(HeaderSet.LENGTH, new Long(obj.length));

     // Initiate the PUT request
     Operation op = conn.put(head);

     // Open the output stream to put the object to it
     OutputStream out = op.openOutputStream();

     // 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);

     // Get the object from the input stream
     InputStream in = op.openInputStream();

     ByteArrayOutputStream out = new ByteArrayOutputStream();
     int data = in.read();
     while (data != -1) {
         out.write((byte)data);
         data = in.read();
     }

     // End the transaction
     in.close();
     op.close();

     byte[] obj = out.toByteArray();
     out.close();

     return obj;
 }
 

Since:
JDE 4.2.1

Method Summary
 HeaderSet connect(HeaderSet headers)
          Completes an OBEX CONNECT operation.
 HeaderSet createHeaderSet()
          Creates a javax.obex.HeaderSet object.
 HeaderSet delete(HeaderSet headers)
          Performs an OBEX DELETE operation.
 HeaderSet disconnect(HeaderSet headers)
          Completes an OBEX DISCONNECT operation.
 Operation get(HeaderSet headers)
          Performs an OBEX GET operation.
 long getConnectionID()
          Retrieves the connection ID that is being used in the present connection.
 Operation put(HeaderSet headers)
          Performs an OBEX PUT operation.
 void setAuthenticator(Authenticator auth)
          Sets the Authenticator to use with this connection.
 void setConnectionID(long id)
          Sets the connection ID header to include in the request packets.
 HeaderSet setPath(HeaderSet headers, boolean backup, boolean create)
          Completes an OBEX SETPATH operation.
 
Methods inherited from interface javax.microedition.io.Connection
close
 

Method Detail

connect

public HeaderSet connect(HeaderSet headers)
                  throws IOException
Completes an OBEX CONNECT operation. If the headers argument is null, no headers will be sent in the request. This method will never return null.

This method must be called and a successful response code of OBEX_HTTP_OK must be received before put(), get(), setPath(), delete(), or disconnect() may be called. Similarly, after a successful call to disconnect(), this method must be called before calling put(), get(), setPath(), delete(), or disconnect().

Parameters:
headers - the headers to send in the CONNECT request
Returns:
the headers that were returned from the server
Throws:
IOException - if an error occurred in the transport layer; if the client is already in an operation; if this method had already been called with a successful response code of OBEX_HTTP_OK and calls to disconnect() have not returned a response code of OBEX_HTTP_OK; if the headers defined in headers exceed the max packet length
IllegalArgumentException - if headers was not created by a call to createHeaderSet()
Since:
JDE 4.2.1

createHeaderSet

public HeaderSet createHeaderSet()
Creates a javax.obex.HeaderSet object. This object can be used to define header values in a request.
Returns:
a new javax.obex.HeaderSet object
Since:
JDE 4.2.1
See Also:
HeaderSet

delete

public HeaderSet delete(HeaderSet headers)
                 throws IOException
Performs an OBEX DELETE operation. This method will never return null.
Parameters:
headers - the header to send in the DELETE request
Returns:
the headers returned by the server
Throws:
IOException - if an error occurred in the transport layer; if the client is already in an operation; if an OBEX connection does not exist because connect() has not been called; if disconnect() had been called and a response code of OBEX_HTTP_OK was received; if the headers defined in headers exceed the max packet length
IllegalArgumentException - if headers were not created by a call to createHeaderSet()
Since:
JDE 4.2.1

disconnect

public HeaderSet disconnect(HeaderSet headers)
                     throws IOException
Completes an OBEX DISCONNECT operation. If the headers argument is null, no headers will be sent in the request. This method will end the session. A new session may be started by calling connect(). This method will never return null.
Parameters:
headers - the header to send in the DISCONNECT request
Returns:
the headers returned by the server
Throws:
IOException - if an error occurred in the transport layer; if the client is already in an operation; if an OBEX connection does not exist because connect() has not been called; if disconnect() has been called and received a response code of OBEX_HTTP_OK after the last call to connect(); if the headers defined in headers exceed the max packet length
IllegalArgumentException - if headers were not created by a call to createHeaderSet()
Since:
JDE 4.2.1

get

public Operation get(HeaderSet headers)
              throws IOException
Performs an OBEX GET operation. This method will send the OBEX headers provided to the server and return an Operation object to continue with the operation. This method will never return null.
Parameters:
headers - the OBEX headers to send as part of the initial GET request
Returns:
the OBEX operation that will complete the GET request
Throws:
IOException - if an error occurred in the transport layer; if an OBEX connection does not exist because connect() has not been called; if disconnect() had been called and a response code of OBEX_HTTP_OK was received; if connect() has not been called; if the client is already in an operation;
IllegalArgumentException - if headers were not created by a call to createHeaderSet()
Since:
JDE 4.2.1
See Also:
Operation

getConnectionID

public long getConnectionID()
Retrieves the connection ID that is being used in the present connection. This method will return -1 if no connection ID is being used.
Returns:
the connection ID being used or -1 if no connection ID is being used
Since:
JDE 4.2.1

put

public Operation put(HeaderSet headers)
              throws IOException
Performs an OBEX PUT operation. This method will send the OBEX headers provided to the server and return an Operation object to continue with the PUT operation. This method will never return null.
Parameters:
headers - the OBEX headers to send in the initial PUT request
Returns:
the operation object used to complete the PUT request
Throws:
IOException - if an error occurred in the transport layer; if an OBEX connection does not exist because connect() has not been called; if disconnect() had been called and a response code of OBEX_HTTP_OK was received; if connect() has not been called; if the client is already in an operation;
IllegalArgumentException - if headers were not created by a call to createHeaderSet()
Since:
JDE 4.2.1
See Also:
Operation

setAuthenticator

public void setAuthenticator(Authenticator auth)
Sets the Authenticator to use with this connection. The Authenticator allows an application to respond to authentication challenge and authentication response headers. If no Authenticator is set, the response to an authentication challenge or authentication response header is implementation dependent.
Parameters:
auth - the Authenticator to use for this connection
Throws:
NullPointerException - if auth is null
Since:
JDE 4.2.1

setConnectionID

public void setConnectionID(long id)
Sets the connection ID header to include in the request packets. If a connection ID is set, it will be sent in each request to the server except for the CONNECT request. An application only needs to set the connection ID if it is trying to operate with different targets over the same transport layer connection. If a client receives a connection ID from the server, the implementation will continue to use that connection ID until the application changes it or until the connection is closed.
Parameters:
id - the connection ID to use
Throws:
IllegalArgumentException - if id is not in the range 0 to 232-1
Since:
JDE 4.2.1

setPath

public HeaderSet setPath(HeaderSet headers,
                         boolean backup,
                         boolean create)
                  throws IOException
Completes an OBEX SETPATH operation. This method will never return null.
Parameters:
backup - if true, instructs the server to back up one directory before moving to the directory specified in name (similar to cd .. on PCs); if false, apply name to the current directory
create - if true, instructs the server to create the directory if it does not exist; if false, instruct the server to return an error code if the directory does not exist
headers - the headers to include in the SETPATH request
Returns:
the headers that were returned from the server
Throws:
IOException - if an error occurred in the transport layer; if the client is already in an operation; if an OBEX connection does not exist because connect() has not been called; if disconnect() had been called and a response code of OBEX_HTTP_OK was received; if the headers defined in headers exceed the max packet length
IllegalArgumentException - if headers were not created by a call to createHeaderSet()
Since:
JDE 4.2.1



Copyright 1999-2009 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.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.