com.stc.connector.sagadapter.jni.sag
Class Handle

java.lang.Object
  com.stc.connector.sagadapter.jni.sag.Handle

public class Handle
extends java.lang.Object

Wrapper class for the SAG C++ Handle class. It is derived from sagapp.hpp. When an application sends a request message, it plays the role of a client. When it receives a request message, it plays the role of a server. An application can play both roles. A client application uses one or more (client) handles. A server application uses one or more (server) handles. An application that is client and server can use the same handles for both traffics. If a client application sends a request message through one handle, it will receive the corresponding response message through the same handle. If a server application receives a request message through one handle, it must send back the response message through the same handle. It not, the message is rejected.

Version:

cvs revision: $Revision: 1.4 $ Last Modified: $Date: 2007/10/19 19:48:39 $

Author:

Harry Liu (harry.liu@sun.com)

Method Summary

void	call(Message request, Message response) This method will send the input request Message object and return the resulting response message stored in the input response Message object.
void	connect() This function establishes the connection.
void	connect(java.lang.String args) This function establishes the connection.
void	disconnect() This function disconnects the connection but keeps the handle object.
void	free() Method free.
long	getAnyResponse(long timeout, Message response) This method will attempt to retrieve the first available response Message object from SAG.
long	getAnyResponse(Message response) This method will attempt to retrieve the first available response Message object from SAG.
long	getRequest(long timeout, Message request) Method getRequest.
long	getRequest(Message request) This method will return the request message and token if successful.
void	getResponse(long timeout, long token, Message response) This method will attempt to retrieve the response Message object associated with the input reconciliation token.
void	getResponse(long token, Message response) This method will attempt to retrieve the response Message object assicated with the input reconciliation token.
void	putError(long token, long errorCode, java.lang.String errorData) This method uses the reconciliation token return by "getRequest" and sends the corresponding error signal.
long	putRequest(Message message) This method will send a request message to SAG.
void	putResponse(long token, Message response) This method uses the reconciliation token return by "getRequest" and sends the corresponding response message.
void	subscribe(java.lang.String address)
void	subscribe(java.lang.String address, java.lang.String arguments)
void	unsubscribe(java.lang.String address)

Methods inherited from class java.lang.Object

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

Method Detail

free

public void free()

Method free.

connect

public void connect()
             throws ExcStatus

This function establishes the connection.

Throws:

ExcStatus - on error

connect

public void connect(java.lang.String args)
             throws ExcStatus

This function establishes the connection.

Parameters:

args - Argument passing for future use. Must be an empty string with SAG 6.0.0.

Throws:

ExcStatus - on error

disconnect

public void disconnect()
                throws ExcStatus

This function disconnects the connection but keeps the handle object. All the methods get that are currently executing by threads will immediately return with an error indication.

Throws:

ExcStatus - on error

putRequest

public long putRequest(Message message)
                throws ExcStatus

This method will send a request message to SAG.

Parameters:

message - The request message to be sent

Returns:

Returns a token associated with the request

Throws:

ExcStatus - on error

getAnyResponse

public long getAnyResponse(Message response)
                    throws ExcStatus

This method will attempt to retrieve the first available response Message object from SAG. The reconciliation token of the associated response Message object will be returned if successful.

Parameters:

response - Response message that is received

Returns:

Reconciliation returned by method "putRequest". The method "getResponse" will return only the response associated to this token.

Throws:

ExcStatus - on error

getAnyResponse

public long getAnyResponse(long timeout,
                           Message response)
                    throws ExcStatus

This method will attempt to retrieve the first available response Message object from SAG. A timeout value may be specified to control the maximum amount of time the method will block for before returning. The reconciliation token of the associated response Message object will be returned if successful.

Parameters:

timeout - The maximum time to wait for a response

response - The resulting response object. The user must create and pass in their own Message object to call this method.

Returns:

The reconciliation token value associated with the returned response Message object.

Throws:

ExcStatus - on error

getResponse

public void getResponse(long token,
                        Message response)
                 throws ExcStatus

This method will attempt to retrieve the response Message object assicated with the input reconciliation token.

Parameters:

token - The token returned from a previous call to putRequest

response - The resulting response object. The user must create and pass in their own Message object to call this method.

Throws:

ExcStatus - on error

getResponse

public void getResponse(long timeout,
                        long token,
                        Message response)
                 throws ExcStatus

This method will attempt to retrieve the response Message object associated with the input reconciliation token. A timeout value may be specified to control the length of time the method will block for before returning.

Parameters:

timeout - The maximum time to wait for a response

token - The token value returned from a previous call to putRequest

response - The resulting response object. The user must create and pass in their own Message object to call this method.

Throws:

ExcStatus - on error

call

public void call(Message request,
                 Message response)
          throws ExcStatus

This method will send the input request Message object and return the resulting response message stored in the input response Message object.

Parameters:

request - Request message

response - The resulting response value of executing the request. User must create and pass in there own Message object

Throws:

ExcStatus - on error

subscribe

public void subscribe(java.lang.String address)
               throws ExcStatus

Throws:

ExcStatus

subscribe

public void subscribe(java.lang.String address,
                      java.lang.String arguments)
               throws ExcStatus

Throws:

ExcStatus

unsubscribe

public void unsubscribe(java.lang.String address)
                 throws ExcStatus

Throws:

ExcStatus

getRequest

public long getRequest(Message request)
                throws ExcStatus

This method will return the request message and token if successful.

Parameters:

request - Request message that is received

Returns:

Reconciliation token associated to the request message

Throws:

ExcStatus

getRequest

public long getRequest(long timeout,
                       Message request)
                throws ExcStatus

Method getRequest.

Parameters:

timeout - long

request - Message

Returns:

long

Throws:

ExcStatus - on error

putResponse

public void putResponse(long token,
                        Message response)
                 throws ExcStatus

This method uses the reconciliation token return by "getRequest" and sends the corresponding response message.

Parameters:

token - Reconciliation token returned by "getRequest"

response - Response message to send back

Throws:

ExcStatus - on error

putError

public void putError(long token,
                     long errorCode,
                     java.lang.String errorData)
              throws ExcStatus

This method uses the reconciliation token return by "getRequest" and sends the corresponding error signal.

Parameters:

token - Reconciliation token returned by "getRequest"

errorCode - Error code (0: Local authentication; 1: No server business response)

errorData - Error data that can be given back.

Throws:

ExcStatus - on error