Sun Adapter for SAG API

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

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

Sun Adapter for SAG API

Copyright © 2008 Sun Microsystems, Inc. All rights reserved.