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 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 security definition, and model queue name and then attaches to the Roma network.
RomaClient(java.lang.String name, int opts, RomaSecurityDef sec, java.lang.String modelQName, RomaILSData ilsData)
          Constructs a named Client, with the specified application options, security definition, model queue name and data to hand off to the transport data structure ILS, and attaches to the Roma network.
RomaClient(java.lang.String name, int opts, RomaSecurityDef sec, java.lang.String modelQName, RomaILSData ilsData, RomaDirectoryAccess dirAccess)
          Constructs a named Client, with the specified application options, security definition, model queue name, data to hand off to the transport data structure ILS and LDAP authentication information, 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.
 void connect(java.lang.String name, int opts, RomaSecurityDef sec, java.lang.String modelQName, RomaILSData ilsData)
          Attach to the Roma network.
 void connect(java.lang.String name, int options, RomaSecurityDef secDef, java.lang.String modelQName, RomaILSData ilsData, RomaDirectoryAccess dirAccess)
          Attach to the Roma network.
protected  RomaClientResponse createResponse(RomaClientResponse resp)
          Invoked in get() methods once the response has been retrieved from the Roma network.
 void deletePublication(RomaPublication pub)
          Deletes a retained publication.
 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.
 RomaILSData getILSData()
          Gets any data an inline service has made available to the application on initialization.
 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 publish(RomaPublication pub)
          Analagous to a put, but the publication is "broadcast" to any application that has subscribed to receive messages on the subject contained within the RomaPublication object.
 void put(RomaClientRequest req)
          Puts a request to a Business Service.
 RomaThemeInfo queryTheme(RomaTheme theme)
          Returns information on the specified theme.
 void requestUpdates(RomaSubscription subscr)
          Request any new publications since the last request update request.
 void subscribe(RomaClientRequest req, RomaSubject subject)
          Subscribe to the specified subject.
 void subscribe(RomaSubscription subscr)
          Subscribe to receive publications sent with the subject defined within the RomaSubscription object.
 void unsubscribe(RomaClientRequest req, RomaSubject subject)
          Unsubscribe to the specified subject.
 void unsubscribe(RomaSubscription subscr)
          Unsubscribe to receive publications sent with the subject defined within the RomaSubscription object.
 void unsubscribeAll(RomaSubscription subscr)
          Unsubscribes for all subjects.
 
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, writeSysLog
 
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 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 security definition, and model queue name and then 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.

RomaClient

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

RomaClient

public RomaClient(java.lang.String name,
                  int opts,
                  RomaSecurityDef sec,
                  java.lang.String modelQName,
                  RomaILSData ilsData,
                  RomaDirectoryAccess dirAccess)
           throws RomaError
Constructs a named Client, with the specified application options, security definition, model queue name, data to hand off to the transport data structure ILS and LDAP authentication information, and attaches to the Roma network.
Parameters:
name - name of the new Client.
opts - application options
sec - security options
modelQName - model queue name
ilsData - data to hand off to the ILS
dirAccess - LDAP authentication information
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, no security definition and no ILS data is 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 and 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 and model name name 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

connect

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

connect

public void connect(java.lang.String name,
                    int options,
                    RomaSecurityDef secDef,
                    java.lang.String modelQName,
                    RomaILSData ilsData,
                    RomaDirectoryAccess dirAccess)
             throws RomaError
Attach to the Roma network. The specified application options, security definition, model queue name, ILS data and LDAP authentication information are associated with it.
Parameters:
name - name of the Client
options - application options
secDef - security definition
modelQName - model queue name
ilsData - data to hand off to the ILS
dirAccess - LDAP authentication information
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. New applications should use the version of publish that takes a RomaPublication as the parameter. This version of the interface may be deprecated in a later version of eBP.

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. New applications should use the version of subscribe that takes a RomaSubscription as the parameter. This version of the interface may be deprecated in a later version of eBP.

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. New applications should use the version of subscribe that takes a RomaSubscription as the parameter. This version of the interface may be deprecated in a later version of eBP.

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.

publish

public void publish(RomaPublication pub)
             throws RomaError
Analagous to a put, but the publication is "broadcast" to any application that has subscribed to receive messages on the subject contained within the RomaPublication object. Publications can be retained.

Parameters:
pub - defined service name and the data to be published.
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs

subscribe

public void subscribe(RomaSubscription subscr)
               throws RomaError
Subscribe to receive publications sent with the subject defined within the RomaSubscription object. The subscription object can also define that client should only get new publication messages, and/or only get publications when the client requests them.

Parameters:
subscr - defines the service name and subject.
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

unsubscribe

public void unsubscribe(RomaSubscription subscr)
                 throws RomaError
Unsubscribe to receive publications sent with the subject defined within the RomaSubscription object.

Parameters:
subscr - defines the service name and subject.
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

requestUpdates

public void requestUpdates(RomaSubscription subscr)
                    throws RomaError
Request any new publications since the last request update request.

Parameters:
subscr - defines the service name and subject
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

deletePublication

public void deletePublication(RomaPublication pub)
                       throws RomaError
Deletes a retained publication.

Parameters:
pub - defines the service name and subject
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

unsubscribeAll

public void unsubscribeAll(RomaSubscription subscr)
                    throws RomaError
Unsubscribes for all subjects.

Parameters:
subscr - defines the service name - the subject is ignored
Throws:
RomaError - is thrown if a Roma operation fails or a marshalling error occurs.

getILSData

public RomaILSData getILSData()
                       throws RomaError
Gets any data an inline service has made available to the application on initialization. Currently, only transport data structure ILSs are able to provide information at this point.
Throws:
RomaError - is thrown on operation failure

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.