com.softwareag.entirex.aci

Class RPCService

java.lang.Object

com.softwareag.entirex.aci.BrokerService

com.softwareag.entirex.aci.RPCService

Direct Known Subclasses:

XMLRPCService

public abstract class RPCService
extends BrokerService

This abstract subclass of BrokerService represents a Broker service used by EntireX RPC. The client stub and server stub generated by the Java Wrapper are subclasses of RPCService.
You should not call the methods of the superclass BrokerService directly.

Since:

EntireX 5.2.1

Field Summary

Fields

Modifier and Type	Field and Description
static int	RELIABLE_AUTO_COMMIT RELIABLE_AUTO_COMMIT = 1
static int	RELIABLE_CLIENT_COMMIT RELIABLE_CLIENT_COMMIT = 2
static int	RELIABLE_OFF RELIABLE_OFF = 0
static int	RPC_MAX_VERSION Highest version supported, always 4 digits.
static java.lang.String	RPC_MAX_VERSION_STRING

Fields inherited from class com.softwareag.entirex.aci.BrokerService

DEFAULT_WAITTIME

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	RPCService() Creates an RPCService object without parameters.
protected	RPCService(BrokerService brokerService, java.lang.String libName, boolean compress) Creates an RPCService object.
protected	RPCService(Broker broker, java.lang.String serverAddr, java.lang.String libName) Creates an RPCService object.
protected	RPCService(Broker broker, java.lang.String serverAddr, java.lang.String libName, boolean compress) Creates an RPCService object.

Method Summary

Methods

Modifier and Type	Method and Description
void	closeConversation() Closes the running RPC conversation.
void	closeConversationCommit() Closes the running RPC conversation.
boolean	getCompression() Returns the current setting for compression.
protected Conversation	getConversation() Returns the Conversation object.
java.lang.String	getLibraryName() Returns the current value of the library name used by the RPC.
java.lang.String	getMessageID() Gets the message id (valid for reliable RPC).
boolean	getNaturalLogon() Returns the current setting for logon to Natural Security for Natural RPC servers.
java.lang.String	getProgramName() Returns the current value of the RPC subprogram name.
int	getReliable() Gets the mode for reliable RPC.
java.lang.String	getRPCPassword() Gets the RPC password (used with NATURAL logon).
java.lang.String	getRPCUserId() Returns the user ID which is used by the RPCs.
java.lang.String	getStatusOfMessage(java.lang.String messageID) Gets the status of the message identified by the message id (valid for reliable RPC).
protected void	onEnter(java.lang.String progname) User exit method called at the beginning of a generated method.
protected void	onException(java.lang.String progname, BrokerException exception) User exit method called when an exception which is an instance of BrokerException is thrown in the generated method.
protected void	onLeave(java.lang.String progname, int sendLength, int receiveLength) User exit method called at the end of a generated method.
protected boolean	onRetry(java.lang.String progname, BrokerException exception) User exit method called when an exception which is an instance of BrokerException is thrown in the generated method.
java.lang.String	ping() Sends an RPC PING command to the service and returns the response string.
void	reliableCommit() Commit a transaction (unit of work) for reliable RPC.
void	reliableRollback() Roll back a transaction (unit of work) for reliable RPC.
void	setBroker(Broker broker) Dynamically assigns the instance of a Broker object.
void	setCompression(boolean rpcCompression) Switches RPC compression ON or OFF.
void	setConversation(Conversation conversation) Enables conversational RPC.
void	setLibraryName(java.lang.String libName) Changes the library name used by the RPC.
void	setNaturalLogon(boolean logon) Enables or disables logon to Natural Security for Natural RPC servers.
void	setReliable(int mode) Sets reliable RPC mode.
void	setRpcLibrary(java.lang.String libraryName1) Sets the RPC library name which is send to the broker with the RPCLIB keyword.
void	setRPCPassword(java.lang.String password1) Changes the password used for an RPC.
void	setRpcProgram(java.lang.String programName) Sets the RPC program name which is send to the broker with the RPCPGM keyword.
void	setRPCUserId(java.lang.String userId1) Changes the user ID used for an RPC call.
void	setServerAddress(java.lang.String serverAddress) Dynamically assigns the server address.

Methods inherited from class com.softwareag.entirex.aci.BrokerService

cancelallConversations, deregister, deregisterImmediate, endallConversations, getBroker, getCharacterEncoding, getDefaultWaittime, getEnvironment, getMaxReceiveLen, getServerClass, getServerName, getServiceName, isGeneric, receive, receive, receiveAny, receiveAttachInfo, receiveOld, register, registerAttach, replyError, send, sendReceive, sendReceive, setAdjustReceiveLen, setDefaultWaittime, setEnvironment, setMaxReceiveLen, toString, useCodePage, useCodePage

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

RELIABLE_OFF

public static final int RELIABLE_OFF

RELIABLE_OFF = 0

See Also:

Constant Field Values

RELIABLE_AUTO_COMMIT

public static final int RELIABLE_AUTO_COMMIT

RELIABLE_AUTO_COMMIT = 1

See Also:

Constant Field Values

RELIABLE_CLIENT_COMMIT

public static final int RELIABLE_CLIENT_COMMIT

RELIABLE_CLIENT_COMMIT = 2

See Also:

Constant Field Values

RPC_MAX_VERSION

public static final int RPC_MAX_VERSION

Highest version supported, always 4 digits.

See Also:

Constant Field Values

RPC_MAX_VERSION_STRING

public static final java.lang.String RPC_MAX_VERSION_STRING

Constructor Detail

RPCService

protected RPCService(Broker broker,
          java.lang.String serverAddr,
          java.lang.String libName,
          boolean compress)

Creates an RPCService object.

Parameters:

broker - A Broker instance.

serverAddr - The server address (class/name/service).

libName - The default library name.

compress - Compression ON/OFF.

RPCService

protected RPCService(BrokerService brokerService,
          java.lang.String libName,
          boolean compress)

Creates an RPCService object.

Parameters:

brokerService - A BrokerService instance.

libName - The default library name.

compress - Compression ON/OFF.

RPCService

protected RPCService(Broker broker,
          java.lang.String serverAddr,
          java.lang.String libName)

Creates an RPCService object.

Parameters:

broker - A Broker instance.

serverAddr - The server address (class/name/service).

libName - The default library name.

RPCService

protected RPCService()

Creates an RPCService object without parameters.

Method Detail

setRPCUserId

public final void setRPCUserId(java.lang.String userId1)

Changes the user ID used for an RPC call. Default is the user ID specified in the Broker constructor. At the moment this is only used by Natural RPC servers running with Natural Security.

Parameters:

userId1 - The new user ID.

Since:

5.2.1.7

getRPCUserId

public final java.lang.String getRPCUserId()

Returns the user ID which is used by the RPCs.

Returns:

user ID as string.

Since:

5.2.1.7

setRPCPassword

public final void setRPCPassword(java.lang.String password1)

Changes the password used for an RPC. Default is the password specified in the Broker logon method. At the moment this is only used by Natural RPC servers running with Natural Security.

Parameters:

password1 - The new Password.

Since:

5.2.1.7

getRPCPassword

public final java.lang.String getRPCPassword()

Gets the RPC password (used with NATURAL logon).

Returns:

the RPC password.

setBroker

public final void setBroker(Broker broker)
                     throws BrokerException

Dynamically assigns the instance of a Broker object. The method cannot be called during a conversational RPC sequence. Can be used by Java Wrapper Customization classes.

Parameters:

broker - A Broker instance.

Throws:

BrokerException - A BrokerException.

Since:

5.3.1.2

setServerAddress

public final void setServerAddress(java.lang.String serverAddress)
                            throws BrokerException

Dynamically assigns the server address. The method cannot be called during a conversational RPC sequence. Can be used by Java Wrapper Customization classes.

Parameters:

serverAddress - The server address (class/name/service).

Throws:

BrokerException - if called in a conversational RPC sequence.

Since:

5.3.1.2

setLibraryName

public final void setLibraryName(java.lang.String libName)

Changes the library name used by the RPC.

Parameters:

libName - The new library name (maximum 8 characters).

getLibraryName

public java.lang.String getLibraryName()

Returns the current value of the library name used by the RPC.

Returns:

The current library name as a string.

getProgramName

public java.lang.String getProgramName()

Returns the current value of the RPC subprogram name.

Returns:

The current subprogram name as a String.

setNaturalLogon

public final void setNaturalLogon(boolean logon)

Enables or disables logon to Natural Security for Natural RPC servers.

Parameters:

logon - true to enable, false to disable.

getNaturalLogon

public final boolean getNaturalLogon()

Returns the current setting for logon to Natural Security for Natural RPC servers.

Returns:

true if enabled, false if disabled.

setCompression

public final void setCompression(boolean rpcCompression)

Switches RPC compression ON or OFF.

Parameters:

rpcCompression - true if ON, false if OFF.

getCompression

public final boolean getCompression()

Returns the current setting for compression.

Returns:

true if ON, false if OFF.

setRpcProgram

public final void setRpcProgram(java.lang.String programName)

Sets the RPC program name which is send to the broker with the RPCPGM keyword.

Parameters:

programName - the program name.

setRpcLibrary

public final void setRpcLibrary(java.lang.String libraryName1)

Sets the RPC library name which is send to the broker with the RPCLIB keyword.

Parameters:

libraryName1 - the library name.

setConversation

public final void setConversation(Conversation conversation)

Enables conversational RPC. All RPCs going through this instance of the RPCService object will use the Conversation object passed as parameter. The same instance of a Conversation object can be passed to different instances of an RPCService object. They will all run in the same conversation.

Parameters:

conversation - A non-null Conversation object.

Throws:

java.lang.IllegalArgumentException - Thrown if no conversation is specified.

java.lang.IllegalStateException - if this service is already used for reliable RPC.

getConversation

protected final Conversation getConversation()

Returns the Conversation object.

Returns:

Conversation object or null;

closeConversation

public final void closeConversation()
                             throws BrokerException

Closes the running RPC conversation. The RPC server receives a "backout" notification.

Throws:

BrokerException - A BrokerException.

closeConversationCommit

public final void closeConversationCommit()
                                   throws BrokerException

Closes the running RPC conversation. The RPC server receives a "commit" notification.

Throws:

BrokerException - A BrokerException.

reliableCommit

public final void reliableCommit()
                          throws BrokerException

Commit a transaction (unit of work) for reliable RPC.

Throws:

BrokerException - if the broker call to commit the messages fails.

Since:

8.0

reliableRollback

public final void reliableRollback()
                            throws BrokerException

Roll back a transaction (unit of work) for reliable RPC.

Throws:

BrokerException - if the broker call to commit the messages fails.

Since:

8.0

getMessageID

public final java.lang.String getMessageID()

Gets the message id (valid for reliable RPC). The message id changes after reliableCommit() or reliableRollback() in RELIABLE_CLIENT_COMMIT mode and after sending a message in RELIABLE_AUTO_COMMIT mode.

Returns:

the message id.

Since:

8.0

getStatusOfMessage

public final java.lang.String getStatusOfMessage(java.lang.String messageID)
                                          throws BrokerException

Gets the status of the message identified by the message id (valid for reliable RPC). Due to Broker settings the status may be not available after processing the message.

Parameters:

messageID - the message id obtained by a previous call of getMessageID().

Returns:

the status of the message.

Throws:

BrokerException - if the Broker call fails.

Since:

8.0

onEnter

protected void onEnter(java.lang.String progname)
                throws BrokerException

User exit method called at the beginning of a generated method. This method has a default implementation and can be overwritten in the Java Wrapper Customization class.

Parameters:

progname - The RPC program name.

Throws:

BrokerException - A BrokerException.

Since:

5.3.1.2

onLeave

protected void onLeave(java.lang.String progname,
           int sendLength,
           int receiveLength)
                throws BrokerException

User exit method called at the end of a generated method. This method is only called when no exception is thrown. This method has a default implementation and can be overwritten in the Java Wrapper Customization class.

Parameters:

progname - The RPC program name.

sendLength - length of send buffer

receiveLength - length of receive buffer

Throws:

BrokerException - A BrokerException.

Since:

5.3.1.2

onException

protected void onException(java.lang.String progname,
               BrokerException exception)
                    throws BrokerException

User exit method called when an exception which is an instance of BrokerException is thrown in the generated method. After calling this method the exception is thrown again. There is no need to throw the exception in the implementation of this method. This method has a default implementation and can be overriden in the Java Wrapper Customization class.

Parameters:

progname - The RPC program name.

exception - reference to the exception, which is thrown in the generated method.

Throws:

BrokerException - A BrokerException.

Since:

5.3.1.2

onRetry

protected boolean onRetry(java.lang.String progname,
              BrokerException exception)
                   throws BrokerException

User exit method called when an exception which is an instance of BrokerException is thrown in the generated method. This method is only called when the exception is thrown during the processing of the RPC. If this method returns false, the exception will be thrown again and the onException method is called. If this method returns true, the RPC will be executed once again. If the second RPC fails, onException will be called immediately. This method has a default implementation and can be overridden in the Java Wrapper Customization class.

Parameters:

progname - The RPC program name.

exception - reference to the exception which is thrown in the generated method.

Returns:

false as a default implementation.

Throws:

BrokerException - A BrokerException.

Since:

5.3.1.2

ping

public java.lang.String ping()
                      throws BrokerException

Sends an RPC PING command to the service and returns the response string.

Returns:

the response string to the PING command.

Throws:

BrokerException - if a Broker error occurs.

Since:

7.1.1.24

getReliable

public final int getReliable()

Gets the mode for reliable RPC. Allowed values are RELIABLE_OFF, RELIABLE_AUTO_COMMIT, RELIABLE_CLIENT_COMMIT.

Returns:

the mode for reliable RPC

Since:

8.0

setReliable

public final void setReliable(int mode)

Sets reliable RPC mode. Allowed values are RELIABLE_OFF, RELIABLE_AUTO_COMMIT, RELIABLE_CLIENT_COMMIT.

Parameters:

mode - the reliable RPC mode to set

Throws:

java.lang.IllegalStateException - if this service is already used for reliable RPC.

Since:

8.0