com.softwareag.entirex.aci

Class BrokerService

java.lang.Object

com.softwareag.entirex.aci.BrokerService

Direct Known Subclasses:

RPCService

public class BrokerService
extends java.lang.Object

Represents a service that is available through the EntireX Broker and is used by both clients which want to access a service, and by servers which register the services they provide.
An instance of this class is always linked to an instance of a Broker object.

Since:

EntireX 5.2.1

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	DEFAULT_WAITTIME The initial default wait time used in the sendReceive() method call and all receive() method calls.

Constructor Summary

Constructors

Constructor and Description
BrokerService(Broker broker, java.lang.String serverAddr) Creates a new BrokerService object.
BrokerService(Broker broker, java.lang.String serverClass, java.lang.String serverName, java.lang.String serviceName) Creates a new BrokerService object.

Method Summary

Modifier and Type	Method and Description
void	cancelallConversations() Cancels all conversations for this service.
void	deregister() Deregisters a registered BrokerService object from the EntireX Broker.
void	deregisterImmediate() Deregisters a registered BrokerService object from the EntireX Broker.
void	endallConversations() Ends all conversations for this service.
Broker	getBroker() Returns the Broker object to which the service belongs.
java.lang.String	getCharacterEncoding() Gets the character encoding name or null.
java.nio.charset.Charset	getCharset() Gets the Charset used for this service.
java.lang.String	getDefaultWaittime() Returns the default wait time.
int	getMaxReceiveLen() Returns the current maximum receive length.
java.lang.String	getServerClass() Returns the server class.
java.lang.String	getServerName() Returns the server name.
java.lang.String	getServiceName() Returns the service name.
boolean	isGeneric() Returns an indication whether this is a generic service.
BrokerMessage	receive() Receives an incoming request or message.
BrokerMessage	receive(java.lang.String wait) Receives an incoming request or message.
BrokerMessage	receiveAny() Receives an incoming request or message.
BrokerAttachInfo	receiveAttachInfo() Receives for attach servers a notification about waiting clients.
BrokerMessage	receiveOld() Receives an incoming request or message.
void	register() Registers a BrokerService with the EntireX Broker.
void	registerAttach() Registers a Broker Attach Server with the EntireX Broker.
boolean	replyError(java.lang.String errorCode, java.lang.String errorText) Sends a reply with an error code to the Broker.
void	send(BrokerMessage msg) Sends an asynchronous non-conversational message.
BrokerMessage	sendReceive(BrokerMessage msg) Sends a synchronous non-conversational message.
BrokerMessage	sendReceive(BrokerMessage msg, java.lang.String wait) Sends a synchronous non-conversational message.
void	setCharacterEncoding(java.lang.String enc) Sets the character encoding for the payload encoding.
void	setDefaultWaittime(java.lang.String wait) Sets the value of the default wait time field to the argument.
void	setMaxReceiveLen(int len) Sets the current maximum receive length.
java.lang.String	toString() Overrides the toString() method of Object.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_WAITTIME

public static final java.lang.String DEFAULT_WAITTIME

The initial default wait time used in the sendReceive() method call and all receive() method calls. The value is 60 seconds.
The default wait time can be changed using the setDefaultWaittime() method call.
The value 'YES', specified in the general documentation of the broker ACI fields is not allowed for Java components.

Since:

EntireX 5.2.1

See Also:

setDefaultWaittime(java.lang.String), Constant Field Values

Constructor Detail

BrokerService

public BrokerService(Broker broker,
                     java.lang.String serverAddr)

Creates a new BrokerService object.

Parameters:

broker - An instance of a Broker object.

serverAddr - The address of the server in the form "serverClass/serverName/serviceName".

Throws:

java.lang.IllegalArgumentException - Thrown if a parameter is invalid.

Since:

EntireX 5.2.1

See Also:

DEFAULT_WAITTIME

BrokerService

public BrokerService(Broker broker,
                     java.lang.String serverClass,
                     java.lang.String serverName,
                     java.lang.String serviceName)

Creates a new BrokerService object.

Parameters:

broker - An instance of a Broker object.

serverClass - The name of the server class.

serverName - The name of the server.

serviceName - The name of the service.

Throws:

java.lang.IllegalArgumentException - Thrown if a parameter is invalid.

See Also:

DEFAULT_WAITTIME

Method Detail

getBroker

public Broker getBroker()

Returns the Broker object to which the service belongs.

Returns:

An instance of the Broker class.

toString

public final java.lang.String toString()

Overrides the toString() method of Object.

Overrides:

toString in class java.lang.Object

Returns:

The complete service address as a string in the form ServerClass/ServerName/ServiceName.

getServerName

public final java.lang.String getServerName()

Returns the server name.

Returns:

The server name as a string.

getServerClass

public final java.lang.String getServerClass()

Returns the server class.

Returns:

The server class as a string.

getServiceName

public final java.lang.String getServiceName()

Returns the service name.

Returns:

The service name as a string.

getDefaultWaittime

public final java.lang.String getDefaultWaittime()

Returns the default wait time.

Returns:

The default wait time as a String.

Since:

EntireX 5.2.1

See Also:

DEFAULT_WAITTIME

setDefaultWaittime

public final void setDefaultWaittime(java.lang.String wait)

Sets the value of the default wait time field to the argument.

Parameters:

wait - The new value of the default wait time. Allowed values are

• NO No wait time. Control is returned to the caller immediately.
• nS The number of seconds the caller will wait for a reply.
• nM The number of minutes the caller will wait for a reply.
• nH The number of hours the caller will wait for a reply.

In all cases the number n has to be smaller than 100000 and not negative. Setting an illegal value results in an IllegalArgumentException on send, sendReceive, or receive. The value 'YES', specified in the general documentation of the broker ACI fields is illegal for Java components.

Since:

EntireX 5.2.1

See Also:

DEFAULT_WAITTIME

getMaxReceiveLen

public final int getMaxReceiveLen()

Returns the current maximum receive length.

Returns:

The current maximum receive length in number of bytes.

setMaxReceiveLen

public final void setMaxReceiveLen(int len)

Sets the current maximum receive length.
The receive length specifies the maximum number of bytes a receive or sendReceive method can receive. If the returned data is longer than the current maximum receive length, the data is truncated and a BrokerException with errorclass=20 and errorcode=94 is thrown.
This value can only be specified on the BrokerService level.
The default value for the receive length is 7168 bytes.

Parameters:

len - The new receive length in bytes.

isGeneric

public final boolean isGeneric()

Returns an indication whether this is a generic service.
A generic service has one of its identifying fields (ServerClass/ServerName/ServiceName) specified as "*".
register, registerAttach, and send calls are not allowed with generic services.

Returns:

true if this is a generic Service, false otherwise.

register

public final void register()
                    throws BrokerException

Registers a BrokerService with the EntireX Broker.
This method is used by a server application to register the current BrokerService object with the EntireX Broker.
To register a service, the service must be defined in the EntireX Broker attribute file.

Throws:

BrokerException - A Broker exception.

registerAttach

public final void registerAttach()
                          throws BrokerException

Registers a Broker Attach Server with the EntireX Broker.
This method is used to register an Attach Server with EntireX Broker. Use the receiveAttachInfo() method to process attch requests.
To register a service, the service must be defined in the EntireX Broker attribute file.

Throws:

BrokerException - A Broker exception.

See Also:

receiveAttachInfo()

deregister

public final void deregister()
                      throws BrokerException

Deregisters a registered BrokerService object from the EntireX Broker.
This method is used by a server application to deregister the current BrokerService object from the EntireX Broker. No new conversations are accepted for the affected service, but existing ones can continue until they are normally ended.
The application that issues this deregister call must remain active until all conversations are ended.

Throws:

BrokerException - A Broker exception.

deregisterImmediate

public final void deregisterImmediate()
                               throws BrokerException

Deregisters a registered BrokerService object from the EntireX Broker.
This method is used by a server application to deregister the current BrokerService object from the EntireX Broker. The service is removed immediately, all affected conversations are ended and the partners are informed. Any active units of work are backed out.

Throws:

BrokerException - A Broker exception.

send

public final void send(BrokerMessage msg)
                throws BrokerException

Sends an asynchronous non-conversational message.
Sends the message to the Broker without waiting for an answer. Suitable for immediate, one-way messages.

Parameters:

msg - BrokerMessage to send.

Throws:

BrokerException - A Broker exception.

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

See Also:

sendReceive(BrokerMessage, java.lang.String)

sendReceive

public final BrokerMessage sendReceive(BrokerMessage msg)
                                throws BrokerException

Sends a synchronous non-conversational message.
Sends the message to the Broker and waits to receive an answer. The default wait time is used. The answer is returned in the BrokerMessage object. Uses the maximum receive length.

Parameters:

msg - BrokerMessage to send.

Returns:

BrokerMessage the received message.

Throws:

BrokerException - A Broker exception.

Since:

EntireX 5.2.1

See Also:

send(com.softwareag.entirex.aci.BrokerMessage)

sendReceive

public final BrokerMessage sendReceive(BrokerMessage msg,
                                       java.lang.String wait)
                                throws BrokerException

Sends a synchronous non-conversational message.
Sends the message to the Broker and waits the specified time to receive an answer. The answer is returned in the BrokerMessage object. Uses the maximum receive length.

Parameters:

msg - BrokerMessage to send.

wait - A timeout period, how long to wait for an immediate reply, measured in seconds/minutes/hours (depending on the trailing S/M/H character). The value 'YES', specified in the general documentation of the broker ACI fields is not allowed for Java components.

Returns:

BrokerMessage the received message.

Throws:

BrokerException - A Broker exception.

java.lang.IllegalArgumentException - Thrown if no message is specified or parameter is invalid.

See Also:

send(com.softwareag.entirex.aci.BrokerMessage)

receive

public final BrokerMessage receive()
                            throws BrokerException

Receives an incoming request or message.
This receive method will accept only non-conversational messages and new conversations.
The answer is returned in the BrokerMessage object. Uses the maximum receive length.
If this receive call opens a new conversation, an appropriate Conversation object is created automatically. The default wait time determines how long to wait for messages.

Returns:

A BrokerMessage object.

Throws:

BrokerException - A Broker exception.

Since:

EntireX 5.2.1

receive

public final BrokerMessage receive(java.lang.String wait)
                            throws BrokerException

Receives an incoming request or message.
This receive method will accept only non-conversational messages and new conversations.
The answer is returned in the BrokerMessage object. Uses the maximum receive length.
If this receive call opens a new conversation, an appropriate Conversation object is created automatically.

Parameters:

wait - A timeout period, how long to wait for a receive, measured in seconds/minutes/hours (depending on the trailing S/M/H character). When null or 'NO' is specified, the operation is non-blocked. If no message is available, a Broker Exception with errorclass=74 and errorcode=74 is thrown. The value 'YES' is illegal.

Returns:

A BrokerMessage object.

Throws:

BrokerException - A Broker exception.

java.lang.IllegalArgumentException - Thrown if parameter is invalid.

receiveOld

public final BrokerMessage receiveOld()
                               throws BrokerException

Receives an incoming request or message.
This receive method will accept only messages from existing conversations.
The answer is returned in the BrokerMessage object. Uses the maximum receive length and the default wait time.

Returns:

A BrokerMessage object.

Throws:

BrokerException - A Broker exception.

Since:

EntireX 5.2.1

receiveAny

public final BrokerMessage receiveAny()
                               throws BrokerException

Receives an incoming request or message.
This receive method will accept only non-conversational messages, messages from existing conversations, and new conversations.
The answer is returned in the BrokerMessage object. Uses the maximum receive length and the default wait time.
If this receive call opens a new conversation, an appropriate Conversation object is created automatically.

Returns:

A BrokerMessage object.

Throws:

BrokerException - A Broker exception.

Since:

EntireX 5.2.1

replyError

public final boolean replyError(java.lang.String errorCode,
                                java.lang.String errorText)
                         throws BrokerException

Sends a reply with an error code to the Broker. A server uses this method to indicate an error. If this is an UOW communication the error is set in the user status o the UOW, and the UOW is cancelled and the conversation terminated.

Parameters:

errorCode - the error code (must be 8 characters long).

errorText - the error text.

Returns:

true if the reply is sent and the Broker supports this call. false if the current conversation is cancelled. This is the way to signal an error for Brokers which do not support the function REPLYERROR. In this case errorCode and errorText are ignored.

Throws:

BrokerException - if the Broker replies with an error code or this service is an attach service or a generic service.

java.lang.IllegalArgumentException - if no message is specified.

Since:

7.2.1

endallConversations

public final void endallConversations()
                               throws BrokerException

Ends all conversations for this service. Receives for outstanding messages are possible.

Throws:

BrokerException - if the Broker replies with an error code.

cancelallConversations

public final void cancelallConversations()
                                  throws BrokerException

Cancels all conversations for this service.

Throws:

BrokerException - A Broker exception.

receiveAttachInfo

public final BrokerAttachInfo receiveAttachInfo()
                                         throws BrokerException

Receives for attach servers a notification about waiting clients. A server which has been registered as an attach server is able to obtain information when client requests cannot be handled either because no server is registered for this service or all registered servers are busy.
Calling this method puts the thread into a wait state until either the default wait time expires (BrokerException 0074 0074) or a client request cannot be handled by an active server. In the latter case a new instance of a BrokerAttachInfo object is returned. The attach server can evaluate this information to decide to start a new server instance.
If an attach server has been registered for more than one service, you have to check the serverAddress field in the BrokerAttachInfo object to find the server.

Returns:

A new instance of a BrokerAttachInfo object.

Throws:

BrokerException - A Broker exception.

Since:

EntireX 5.2.1

See Also:

registerAttach()

setCharacterEncoding

public void setCharacterEncoding(java.lang.String enc)
                          throws BrokerException

Sets the character encoding for the payload encoding. The default is the default encoding of your JVM.

Parameters:

enc - the name of the character encoding.

Throws:

BrokerException - if setting the character encoding support fails.

Since:

7.1.1.24

getCharacterEncoding

public java.lang.String getCharacterEncoding()

Gets the character encoding name or null.

Returns:

the current character encoding name.

Since:

7.1.1.24

getCharset

public java.nio.charset.Charset getCharset()

Gets the Charset used for this service.

Returns:

the current Charset.

Since:

10.5