javax.obex
Class ServerRequestHandler

java.lang.Object
  javax.obex.ServerRequestHandler

public class ServerRequestHandler
extends Object

The ServerRequestHandler class defines an event listener that will respond to OBEX requests made to the server.

The onConnect(), onSetPath(), onDelete(), onGet(), and onPut() methods may return any response code defined in the ResponseCodes class except for OBEX_HTTP_CONTINUE. If OBEX_HTTP_CONTINUE or a value not defined in the ResponseCodes class is returned, the server implementation will send an OBEX_HTTP_INTERNAL_ERROR response to the client.

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 Requests

A CREATE-EMPTY request allows clients to create empty objects on the server. When a CREATE-EMPTY request is received, the onPut() method will be called by the implementation. To differentiate between a normal PUT request and a CREATE-EMPTY request, an application must open the InputStream from the Operation object passed to the onPut() method. For a PUT request, the application will be able to read Body data from this InputStream. For a CREATE-EMPTY request, there will be no Body data to read. Therefore, a call to InputStream.read() will return -1.

Since:

BlackBerry API 4.2.1

Constructor Summary
protected	ServerRequestHandler() Creates a ServerRequestHandler.

Method Summary
HeaderSet	createHeaderSet() Creates a HeaderSet object that may be used in put and get operations.
long	getConnectionID() Retrieves the connection ID that is being used in the present connection.
void	onAuthenticationFailure(byte[] userName) Called when this object attempts to authenticate a client and the authentication request fails because the response digest in the authentication response header was wrong.
int	onConnect(HeaderSet request, HeaderSet reply) Called when a CONNECT request is received.
int	onDelete(HeaderSet request, HeaderSet reply) Called when a DELETE request is received.
void	onDisconnect(HeaderSet request, HeaderSet reply) Called when a DISCONNECT request is received.
int	onGet(Operation op) Called when a GET request is received.
int	onPut(Operation op) Called when a PUT request is received.
int	onSetPath(HeaderSet request, HeaderSet reply, boolean backup, boolean create) Called when a SETPATH request is received.
void	setConnectionID(long id) Sets the connection ID header to include in the reply packets.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerRequestHandler

protected ServerRequestHandler()

Creates a ServerRequestHandler.

Since:

BlackBerry API 4.2.1

Method Detail

createHeaderSet

public final HeaderSet createHeaderSet()

Creates a HeaderSet object that may be used in put and get operations.

Returns:

the HeaderSet object to use in put and get operations

Since:

BlackBerry API 4.2.1

setConnectionID

public void setConnectionID(long id)

Sets the connection ID header to include in the reply packets.

Parameters:

id - the connection ID to use; -1 if no connection ID should be sent

Throws:

IllegalArgumentException - if id is not in the range -1 to 2³²-1

Since:

BlackBerry API 4.2.1

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:

BlackBerry API 4.2.1

onConnect

public int onConnect(HeaderSet request,
                     HeaderSet reply)

Called when a CONNECT request is received.

If this method is not implemented by the class that extends this class, onConnect() will always return an OBEX_HTTP_OK response code.

The headers received in the request can be retrieved from the request argument. The headers that should be sent in the reply must be specified in the reply argument.

Parameters:

request - contains the headers sent by the client; request will never be null

reply - the headers that should be sent in the reply; reply will never be null

Returns:

a response code defined in ResponseCodes that will be returned to the client; if an invalid response code is provided, the OBEX_HTTP_INTERNAL_ERROR response code will be used

Since:

BlackBerry API 4.2.1

onDisconnect

public void onDisconnect(HeaderSet request,
                         HeaderSet reply)

Called when a DISCONNECT request is received.

The headers received in the request can be retrieved from the request argument. The headers that should be sent in the reply must be specified in the reply argument.

Parameters:

request - contains the headers sent by the client; request will never be null

reply - the headers that should be sent in the reply; reply will never be null

Since:

BlackBerry API 4.2.1

onSetPath

public int onSetPath(HeaderSet request,
                     HeaderSet reply,
                     boolean backup,
                     boolean create)

Called when a SETPATH request is received.

If this method is not implemented by the class that extends this class, onSetPath() will always return an OBEX_HTTP_NOT_IMPLEMENTED response code.

The headers received in the request can be retrieved from the request argument. The headers that should be sent in the reply must be specified in the reply argument.

Parameters:

request - contains the headers sent by the client; request will never be null

reply - the headers that should be sent in the reply; reply will never be null

backup - true if the client requests that the server back up one directory before changing to the path described by name; false to apply the request to the present path

create - true if the path should be created if it does not already exist; false if the path should not be created if it does not exist and an error code should be returned

Returns:

a response code defined in ResponseCodes that will be returned to the client; if an invalid response code is provided, the OBEX_HTTP_INTERNAL_ERROR response code will be used

Since:

BlackBerry API 4.2.1

onDelete

public int onDelete(HeaderSet request,
                    HeaderSet reply)

Called when a DELETE request is received.

If this method is not implemented by the class that extends this class, onDelete() will always return an OBEX_HTTP_NOT_IMPLEMENTED response code.

The headers received in the request can be retrieved from the request argument. The headers that should be sent in the reply must be specified in the reply argument.

Parameters:

request - contains the headers sent by the client; request will never be null

reply - the headers that should be sent in the reply; reply will never be null

Returns:

a response code defined in ResponseCodes that will be returned to the client; if an invalid response code is provided, the OBEX_HTTP_INTERNAL_ERROR response code will be used

Since:

BlackBerry API 4.2.1

onPut

public int onPut(Operation op)

Called when a PUT request is received.

If this method is not implemented by the class that extends this class, onPut() will always return an OBEX_HTTP_NOT_IMPLEMENTED response code.

If an ABORT request is received during the processing of a PUT request, op will be closed by the implementation.

Parameters:

op - contains the headers sent by the client and allows new headers to be sent in the reply; op will never be null

Returns:

a response code defined in ResponseCodes that will be returned to the client; if an invalid response code is provided, the OBEX_HTTP_INTERNAL_ERROR response code will be used

Since:

BlackBerry API 4.2.1

onGet

public int onGet(Operation op)

Called when a GET request is received.

If this method is not implemented by the class that extends this class, onGet() will always return an OBEX_HTTP_NOT_IMPLEMENTED response code.

If an ABORT request is received during the processing of a GET request, op will be closed by the implementation.

Parameters:

op - contains the headers sent by the client and allows new headers to be sent in the reply; op will never be null

Returns:

a response code defined in ResponseCodes that will be returned to the client; if an invalid response code is provided, the OBEX_HTTP_INTERNAL_ERROR response code will be used

Since:

BlackBerry API 4.2.1

onAuthenticationFailure

public void onAuthenticationFailure(byte[] userName)

Called when this object attempts to authenticate a client and the authentication request fails because the response digest in the authentication response header was wrong.

If this method is not implemented by the class that extends this class, this method will do nothing.

Parameters:

userName - the user name returned in the authentication response; null if no user name was provided in the response

Since:

BlackBerry API 4.2.1