javax.obex
Class ServerRequestHandler

java.lang.Object
  extended by 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 232-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





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.