com.candle.roma.kxc
Class RomaClientRequest

java.lang.Object
  |
  +--com.candle.roma.kxc.RomaClientRequest

public class RomaClientRequest
extends java.lang.Object

This class encapsulates requests made by a Roma client to a Roma business service. It allows the application to set the options and the service required when making a client request. This class also provides a framework for associating application specific data with a client request.

The ClientRequest class may be sub-classed to provide for application specific data. Any subclasses must override the marshalRequest() method to stream application data into the message data buffer.

See Also:
marshalRequest()

Constructor Summary
RomaClientRequest(java.lang.String svcName)
          Constructs request with default options and with the name of a Roma businesss service specified.
RomaClientRequest(java.lang.String svcName, byte[] msgBuf, int msgLen)
          Constructs request with default options, with the name of a Roma businesss service specified and user message buffer.
RomaClientRequest(java.lang.String svcName, byte[] msgBuf, int msgLen, byte[] tagBuf, int tagLen)
          Constructs request with default options, with the name of a Roma businesss service specified and user message buffer.
 
Method Summary
 byte[] correlId()
          Return the message correlation identifier.
 RomaILSData getILSData()
          Get incoming ILS data
 void marshalRequest()
          Invoked from the RomaClient.put() method immediately prior to attempting to issue the request to the Roma network.
 byte[] msgId()
          Return the message identifier in a byte array.
 void setApiProfileName(java.lang.String profile)
          Associates an API profile with the put operation.
 void setCloseTheme(boolean b)
          Specify whether the theme should be closed automatically when the operation completes.
 void setCOA(boolean flag)
          set or clear confirmation of arrival flag
 void setCOD(boolean flag)
          set or clear confirmation of delivery flag
 void setCodepage(int codepage)
          Set a new message codepage value.
 void setCorrelId(byte[] correlId)
          Set the message correlation identifier.
 void setDatagram(boolean b)
          Sets the datagram flag.
 void setEncoding(int encoding)
          Set the message encoding.
 void setErrorProfileName(java.lang.String profile)
          Associates an error profile with the put operation.
 void setExpiry(int expiry)
          Set a new message expiry time.
 void setFeedback(int feedback)
          Sets a new message feedback code.
 void setFormat(int format)
          Set a new message format value.
 void setFormatName(java.lang.String formatName)
          Sets the format name.
 void setILSData(RomaILSData ilsData)
          Set outgoing ILS data
 void setMsgBuffer(byte[] data)
          Sets message data.
 boolean setMsgBuffer(byte[] buffer, int dataLength)
          Set buffer containing the message data and the length of the message for a PUT request.
 void setMsgBuffer(java.lang.String data)
          Sets message data.
 void setMsgId(byte[] msgId)
          Set the message identifier.
 void setMsgName(java.lang.String messageName)
          Set the name of this message
 void setNewTheme(boolean b)
          Specify whether a new theme should be allocated.
 void setNoEms(boolean select)
          Enables or disables the option to send the message to an exception message service if the put operation fails.
 void setNoNotification(boolean select)
          Enables or disables the option to send a notification message back to the sender if the message get operation fails.
 void setNoSyncAllowed(boolean flag)
          Controls whether an MSMQ message can be placed outside syncpoint control.
 void setNoTransformation(boolean select)
          Enables or disables the option to send the message to a message transformation service if the next component in the workflow cannot accept the message format.
 void setPersistence(int persistence)
          Set a new value for the message perisitence.
 void setPriority(int priority)
          Set the message priority.
 void setRetainTheme(boolean b)
          Specify whether the theme should be retained for future operations.
 void setSecurityDef(RomaSecurityDef secDef)
          Set security definition
 void setSelector(int sel)
          Sets the put selector.
 void setServiceName(java.lang.String svcName)
          Sets the name of the Roma Business Service that a put operation will send this request to.
 void setSuppressErrorProfile(boolean b)
          Specify if error profiling is to be suppressed
 void setSyncpointDef(RomaSyncpointDef sync)
          Specify sync point definitiion
 void setTagBuffer(byte[] data)
          Sets tag data.
 boolean setTagBuffer(byte[] buffer, int dataLength)
          Set buffer containing the tag data and the length of the tag for a PUT request.
 void setTagBuffer(java.lang.String data)
          Sets tag data.
 void setTermSupported(boolean b)
          Specify if termination is supported
 void setTheme(RomaTheme theme)
          Update the message theme.
 void setUseApiProfile(boolean b)
          Indicates that flags and options specified in the API profile should be used for the Roma put operation.
 void setUseTheme(boolean b)
          Specify whether an existing theme should be used.
 int status()
          Return message status
 RomaTheme theme()
          Return the message theme.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RomaClientRequest

public RomaClientRequest(java.lang.String svcName)
Constructs request with default options and with the name of a Roma businesss service specified.
Parameters:
svcName - name of a Roma Business Service.

RomaClientRequest

public RomaClientRequest(java.lang.String svcName,
                         byte[] msgBuf,
                         int msgLen)
Constructs request with default options, with the name of a Roma businesss service specified and user message buffer.
Parameters:
svcName - name of a Roma Business Service.
msgBuf - byte array containing the message.
msgLen - length of the message.

RomaClientRequest

public RomaClientRequest(java.lang.String svcName,
                         byte[] msgBuf,
                         int msgLen,
                         byte[] tagBuf,
                         int tagLen)
Constructs request with default options, with the name of a Roma businesss service specified and user message buffer.
Parameters:
svcName - name of a Roma Business Service.
msgBuf - byte array containing the message.
msgLen - length of the message.
tagBuf - byte array containing the tag data.
tagLen - length of the tag data.
Method Detail

setServiceName

public void setServiceName(java.lang.String svcName)
Sets the name of the Roma Business Service that a put operation will send this request to.
Parameters:
svcName - Roma Business Service name.

marshalRequest

public void marshalRequest()
                    throws java.io.IOException
Invoked from the RomaClient.put() method immediately prior to attempting to issue the request to the Roma network. Is intended that this method be overridden in derived classes to provide an implementation for marshalling application specific data into the associated message buffer.

If this method fails the put operation will not be carried out.

Throws:
java.io.IOException - is thrown on error.
See Also:
RomaClient.put(RomaClientRequest)

setSelector

public void setSelector(int sel)
Sets the put selector. This specifies which identifiers contained in the message should be used when the message is put.
Parameters:
sel - the new value of the put selector.

The value will be one of the following fields :-

  • USE_NONE
  • USE_MSGID
  • USE_CORRELID
  • USE_MSGID_AND_CORRELID

setNoSyncAllowed

public void setNoSyncAllowed(boolean flag)
Controls whether an MSMQ message can be placed outside syncpoint control. If the application attempts to put a message to MSMQ inside syncpoint control but the target queue does not support transactions, the call is normally rejected with error code RC_NONXACTIONAL. The application can call this method with true flag to force an MSMQ message to be placed outside syncpoint control.
Parameters:
flag - one of :-
  • true - allow MSMQ messages to be placed outside syncpoint control
  • false - don't allow MSMQ messages to be placed outside syncpoint control

setApiProfileName

public void setApiProfileName(java.lang.String profile)
Associates an API profile with the put operation.
Parameters:
profile - the name of the API profile.

setErrorProfileName

public void setErrorProfileName(java.lang.String profile)
Associates an error profile with the put operation.
Parameters:
profile - the name of the error profile.

setSuppressErrorProfile

public void setSuppressErrorProfile(boolean b)
Specify if error profiling is to be suppressed
Parameters:
b - true to suppress error profiling

setUseApiProfile

public void setUseApiProfile(boolean b)
Indicates that flags and options specified in the API profile should be used for the Roma put operation.

If this option is chosen but the specified profile is not available then default values are used for the put options.


setNoEms

public void setNoEms(boolean select)
Enables or disables the option to send the message to an exception message service if the put operation fails.
Parameters:
select - one of :-
  • true - do not perform a send to an exception message service if put fails.
  • false - allow a message to be sent to an exception message service if the put fails.

setNoNotification

public void setNoNotification(boolean select)
Enables or disables the option to send a notification message back to the sender if the message get operation fails.
Parameters:
select - one of :-
  • true - do not allow a notification message to be sent on a get failure.
  • false - do allow a notification message to be sent.

setNoTransformation

public void setNoTransformation(boolean select)
Enables or disables the option to send the message to a message transformation service if the next component in the workflow cannot accept the message format.
Parameters:
select - one of :-
  • true - do not allow the message to sent to the transformation service.
  • false - allow the message to be routed via a transformation service if necessary.

setTermSupported

public void setTermSupported(boolean b)
Specify if termination is supported
Parameters:
b - true to indicate termination is supported.

setNewTheme

public void setNewTheme(boolean b)
Specify whether a new theme should be allocated.

Parameters:
b - if true then a new theme is allocated.

setRetainTheme

public void setRetainTheme(boolean b)
Specify whether the theme should be retained for future operations.

Parameters:
b - if true then the theme is retained.

setCloseTheme

public void setCloseTheme(boolean b)
Specify whether the theme should be closed automatically when the operation completes.

Parameters:
b - if true then the theme will be closed.

setUseTheme

public void setUseTheme(boolean b)
Specify whether an existing theme should be used.

Parameters:
b - if true then the existing theme is used.

setCOD

public void setCOD(boolean flag)
set or clear confirmation of delivery flag

setCOA

public void setCOA(boolean flag)
set or clear confirmation of arrival flag

setDatagram

public void setDatagram(boolean b)
Sets the datagram flag. Controls type of the request sent to server.

If an API profile is to be used ( selected by invoking the useApiProfile() method and verifiable by querying the isApiProfileUsed() method ) then this setting will be overridden either by the profile or, if not available, the default for this option.

Parameters:
b - one of :-
  • true - send DATAGRAM
  • false - send REQUEST

setPriority

public void setPriority(int priority)
Set the message priority.
Parameters:
priority - this can be one of the following :-
  • PRIORITY_DEFAULT - use the default priority from the transport.
  • PRIORITY_PROFILE - use the priority as specified in the associated Put API profile. If no such profile or attribute, use PRIORITY_DEFAULT.
  • a specific integer meaningful to the underlying transport e.g. 0..9 for MQSeries and BEAMQ, 0..7 for MSMQ

setPersistence

public void setPersistence(int persistence)
Set a new value for the message perisitence.
Parameters:
persistence - this can be one of the following :-
  • PERSISTENCE_YES
  • PERSISTENCE_NO
  • PERSISTENCE_PROFILE - use the persistence value as specified in the associated Put API profile. If no such profile or attribute, use PERSISTENCE_NO.

setFormat

public void setFormat(int format)
Set a new message format value.
Parameters:
format - identifies the format of message. If the value FORMAT_PROFILE is used then the message format value is retrieved from the associated Put API profile. If the profile is not available or else has no format attribute value then the message format value FORMAT_BINARY is used.

setFeedback

public void setFeedback(int feedback)
Sets a new message feedback code.
Parameters:
feedback - new message feedback value.

setExpiry

public void setExpiry(int expiry)
Set a new message expiry time.
Parameters:
expiry - the new expiry time value in seconds or EXPIRY_NEVER or EXPIRY_PROFILE. If EXPIRY_PROFILE is specified then the expiry value is retrieved from the associated Put API profile. If the profile is not available or else has no expiry attribute set, the EXPIRY_NEVER constant is used.

setCodepage

public void setCodepage(int codepage)
Set a new message codepage value.
Parameters:
codepage - the new codepage value. If CODEPAGE_PROFILE is specified then the codepage will be retrieved from the associated Put API profile. If the profile is not available or else has no codepage attribute set, the default value of CODEPAGE_USER will be used.

setEncoding

public void setEncoding(int encoding)
Set the message encoding.
Parameters:
encoding - the new encoding indicator. If this is ENCODING_PROFILE then the value is retrieved from the associated Put API profile. If the profile is not available or else has no encoding attribute set, the default value ENCODING_DEFAULT is used.

setMsgId

public void setMsgId(byte[] msgId)
Set the message identifier.
Parameters:
msgId - a byte array containing the new message id value. The msg id must not exceed kxc.MSG_ID_LENGTH.

msgId

public byte[] msgId()
Return the message identifier in a byte array.

setCorrelId

public void setCorrelId(byte[] correlId)
Set the message correlation identifier.
Parameters:
correlId - the new correlation id.

correlId

public byte[] correlId()
Return the message correlation identifier.

setFormatName

public void setFormatName(java.lang.String formatName)
Sets the format name.
Parameters:
formatName - the new format name.

setTheme

public void setTheme(RomaTheme theme)
Update the message theme.
Parameters:
theme - RomaTheme object.

theme

public RomaTheme theme()
Return the message theme. Theme can be set internally when the message is being sent or received or else explicitly by the user.

setMsgName

public void setMsgName(java.lang.String messageName)
Set the name of this message
Parameters:
messageName - name to be used

status

public int status()
Return message status

setMsgBuffer

public boolean setMsgBuffer(byte[] buffer,
                            int dataLength)
Set buffer containing the message data and the length of the message for a PUT request. To send an empty message set length to 0 and buffer to null
Parameters:
buffer - byte array containing the message.
dataLength - length of the message.
Returns:
true if successfull, false if datalength < 0 or datalength = 0 and buffer != null

setMsgBuffer

public void setMsgBuffer(byte[] data)
Sets message data.
Parameters:
data - Message data

setMsgBuffer

public void setMsgBuffer(java.lang.String data)
Sets message data.
Parameters:
data - Message data

setTagBuffer

public boolean setTagBuffer(byte[] buffer,
                            int dataLength)
Set buffer containing the tag data and the length of the tag for a PUT request.
Parameters:
buffer - byte array containing the message.
dataLength - length of the message.
Returns:
true if successfull, false if datalength < 0 or datalength = 0 and buffer != null

setTagBuffer

public void setTagBuffer(byte[] data)
Sets tag data.
Parameters:
data - Tag data

setTagBuffer

public void setTagBuffer(java.lang.String data)
Sets tag data.
Parameters:
data - Tag data

setSecurityDef

public void setSecurityDef(RomaSecurityDef secDef)
Set security definition
Parameters:
secDef - security definition to be sent with message

setSyncpointDef

public void setSyncpointDef(RomaSyncpointDef sync)
Specify sync point definitiion

Parameters:
sync - definition to be used.

setILSData

public void setILSData(RomaILSData ilsData)
Set outgoing ILS data
Parameters:
ilsData - The ILS data to be sent with message

getILSData

public RomaILSData getILSData()
Get incoming ILS data