com.candle.roma.kxc
Class RomaClient

java.lang.Object
  |
  +--com.candle.roma.kxc.RomaContext
        |
        +--com.candle.roma.kxc.RomaClient

public class RomaClient
extends RomaContext

This class represents the application's client-side use of Roma.

A single application is allowed to instantiate multiple objects of the RomaClient class.

A RomaClient can issue requests to a Business Service and can get responses.

A client can also commit and rollback transactions.

It is intended that the RomaClient class be extended by application programmers to differentiate between different kinds of responses. To do this the application programmer must provide a new implementation of the createResponse() method that determines what kind of RomaClientResponse has been received by looking at the incoming message attributes such as the message format or message identifier. The application programmer may then create an appropriate type of RomaClientResponse that has application-specific instructions for the unmarshalling of the message data.

See Also:
RomaClientResponse

Constructor Summary
RomaClient()
          Constructs a new RomaClient object but does not attach to the Roma network.
RomaClient(java.lang.String name)
          Constructs a named Client and attaches to the Roma network using default application options and with no security definition.
RomaClient(java.lang.String name, int opts)
          Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
RomaClient(java.lang.String name, int opts, RomaSecurityDef sec)
          Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
RomaClient(java.lang.String name, int opts, RomaSecurityDef sec, java.lang.String modelQName)
          Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
 
Method Summary
 RomaTheme buildTheme(RomaTheme theme, RomaThemeInfo info, int options, boolean close)
          Creates a new theme from the source theme and the specified theme information.
 void connect(java.lang.String name)
          Attaches a named Client to the Roma network.
 void connect(java.lang.String name, int opts)
          Attach to the Roma network.
 void connect(java.lang.String name, int opts, RomaSecurityDef sec)
          Attach to the Roma network.
 void connect(java.lang.String name, int opts, RomaSecurityDef sec, java.lang.String modelQName)
          Attach to the Roma network.
protected  RomaClientResponse createResponse(RomaClientResponse resp)
          Invoked in get() methods once the response has been retrieved from the Roma network.
 RomaClientResponse get()
          Gets the response to an earlier Client using default options.
 RomaClientResponse get(RomaGetOptions opt)
          Gets the response to an earlier Client request using supplied options.
 RomaClientResponse get(RomaGetOptions opt, byte[] msgBuf, RomaInteger msgBufSize, byte[] tagBuf, RomaInteger tagBufSize)
          Gets the response to an earlier Client request request using supplied options.
 RomaMessageInfo interpretMessage(RomaClientResponse msg, int options)
          Returns detailed information on the specified message.
 void publish(RomaClientRequest req, RomaSubject subject)
          Analagous to a put, but the request is treated as a publication on the specified subject.
 void put(RomaClientRequest req)
          Puts a request to a Business Service.
 RomaThemeInfo queryTheme(RomaTheme theme)
          Returns information on the specified theme.
 void subscribe(RomaClientRequest req, RomaSubject subject)
          Subscribe to the specified subject.
 void unsubscribe(RomaClientRequest req, RomaSubject subject)
          Unsubscribe to the specified subject.
 
Methods inherited from class com.candle.roma.kxc.RomaContext
closeTheme, commitLocal, copyTheme, deleteStorageQueue, disconnect, insertWorkflow, isConnected, mergeEteInfo, putException, putException, replaceWorkflow, reportError, reportError, rollbackLocal, sendAlert, setBusinessFlow, writeLog
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RomaClient

public RomaClient()
Constructs a new RomaClient object but does not attach to the Roma network.

Call method connect() to attach to the Roma network.


RomaClient

public RomaClient(java.lang.String name)
           throws RomaError
Constructs a named Client and attaches to the Roma network using default application options and with no security definition.
Parameters:
name - name of the new Client.
Throws:
RomaError - is thrown on operation failure.

RomaClient

public RomaClient(java.lang.String name,
                  int opts)
           throws RomaError
Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
Parameters:
name - name of the new Client.
opts - application options
Throws:
RomaError - is thrown on operation failure.

RomaClient

public RomaClient(java.lang.String name,
                  int opts,
                  RomaSecurityDef sec)
           throws RomaError
Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
Parameters:
name - name of the new Client.
opts - application options
sec - security options
Throws:
RomaError - is thrown on operation failure.

RomaClient

public RomaClient(java.lang.String name,
                  int opts,
                  RomaSecurityDef sec,
                  java.lang.String modelQName)
           throws RomaError
Constructs a named Client, with the specified application options and security definition, and attaches to the Roma network.
Parameters:
name - name of the new Client.
opts - application options
sec - security options
modelQName - model queue name
Throws:
RomaError - is thrown on operation failure.
Method Detail

connect

public void connect(java.lang.String name)
             throws RomaError
Attaches a named Client to the Roma network. Default application options and no security definition are used in the connect operation.
Parameters:
name - name of the Client.name
Throws:
RomaError - is thrown on operation failure

connect

public void connect(java.lang.String name,
                    int opts)
             throws RomaError
Attach to the Roma network. The specified application options security definition are associated with it.
Parameters:
name - name of the Client
opts - application options
Throws:
RomaError - is thrown on operation failure

connect

public void connect(java.lang.String name,
                    int opts,
                    RomaSecurityDef sec)
             throws RomaError
Attach to the Roma network. The specified application options security definition are associated with it.
Parameters:
name - name of the Client
opts - application options
sec - security definition
Throws:
RomaError - is thrown on operation failure

connect

public void connect(java.lang.String name,
                    int opts,
                    RomaSecurityDef sec,
                    java.lang.String modelQName)
             throws RomaError
Attach to the Roma network. The specified application options security definition are associated with it.
Parameters:
name - name of the Client
opts - application options
sec - security definition
modelQName - model queue name
Throws:
RomaError - is thrown on operation failure

put

public void put(RomaClientRequest req)
         throws RomaError
Puts a request to a Business Service.

This method calls the ClientRequest class' marshalRequest() method immediately before issuing the request. If the put succeeds the RomaClientRequest instance is updated with the generated theme and/or the message id and correlation id if the user did not specified them on the request.

Parameters:
req - the RomaClientRequest to be put. This provides the options and the data for the put operation.
Throws:
RomaError - is thrown on operation failure

get

public RomaClientResponse get()
                       throws RomaError
Gets the response to an earlier Client using default options. supplied get options.

If the wait interval has expired a null RomaClientResponse is returned.

Throws:
RomaError - is thrown on operation failure

get

public RomaClientResponse get(RomaGetOptions opt)
                       throws RomaError
Gets the response to an earlier Client request using supplied options. If the get options have not been used to select a specific response the first available response is retrieved. If the wait interval has expired a null RomaClientResponse is returned.
Parameters:
opt - chooses the response
Throws:
RomaError - is thrown on operation failure

get

public RomaClientResponse get(RomaGetOptions opt,
                              byte[] msgBuf,
                              RomaInteger msgBufSize,
                              byte[] tagBuf,
                              RomaInteger tagBufSize)
                       throws RomaError
Gets the response to an earlier Client request request using supplied options. The supplied message and tag buffers will be used to receive data. If the wait interval has expired a null RomaClientResponse is returned.
Parameters:
opt - chooses the response
msgBuf - buffer to receive message
msgBufSize - size of message buffer.
tagBuf - buffer to receive tag data
tagBufSize - size of buffer to receive tag data
Throws:
RomaError - is thrown on operation failure

publish

public void publish(RomaClientRequest req,
                    RomaSubject subject)
             throws RomaError
Analagous to a put, but the request is treated as a publication on the specified subject.

Parameters:
req - defined service name and the data to be published.
subject - specifies the subject for this publication.
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs

subscribe

public void subscribe(RomaClientRequest req,
                      RomaSubject subject)
               throws RomaError
Subscribe to the specified subject. Any data in the request message is ignored.

Parameters:
req - defines the service name.
subject - the subject to be subscribed to (can include wildcards)
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

unsubscribe

public void unsubscribe(RomaClientRequest req,
                        RomaSubject subject)
                 throws RomaError
Unsubscribe to the specified subject. Any data in the request message is ignored.

Parameters:
req - defines the service name.
subject - the subject to be unsubscribed to (can include wildcards)
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

queryTheme

public RomaThemeInfo queryTheme(RomaTheme theme)
                         throws RomaError
Returns information on the specified theme.
Parameters:
theme - Source theme
Throws:
RomaError - is thrown if the operation fails

buildTheme

public RomaTheme buildTheme(RomaTheme theme,
                            RomaThemeInfo info,
                            int options,
                            boolean close)
                     throws RomaError
Creates a new theme from the source theme and the specified theme information.
Parameters:
theme - Source theme
info - Theme information
options - Options indicating what parts of the theme information to use for the theme build. It is THEMEINFO_ALL or a combination of
  • Roma.THEMEINFO_THEMEID - use theme ID
  • Roma.THEMEINFO_RETRYCOUNT - use retry count
  • Roma.THEMEINFO_WORKFLOW - use workflow information
  • Roma.THEMEINFO_ETEINFO - use ETE information
  • Roma.THEMEINFO_TRAILERS - use persistent trailers
  • Roma.THEMEINFO_CONFIRMFLAGS - use confirmation flags
close - If true, closes the source theme
Throws:
RomaError - is thrown if the operation fails

interpretMessage

public RomaMessageInfo interpretMessage(RomaClientResponse msg,
                                        int options)
                                 throws RomaError
Returns detailed information on the specified message.
Parameters:
msg - Source message
options - Feature options, should be zero or one of
  • Roma.INTMSG_THEME - extract the message theme. The application is responsible for the theme closing.
Throws:
RomaError - is thrown if the operation fails

createResponse

protected RomaClientResponse createResponse(RomaClientResponse resp)
Invoked in get() methods once the response has been retrieved from the Roma network.

It is intended that this method is overridden in subclasses to differentiate between different types of response.

Users can construct subclasses of RomaClientResponse classes that deal with the application-specific response data as appropriate.

The overriddden createResponse() method can construct the appropriate type of RomaClientResponse using the RomaClientResponse instance data.

Parameters:
resp - RomaClientResponse containing raw response data.
Returns:
a RomaClientResponse or null if failure has occurred when constructing the RomaClientResponse subclass.