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

static java.lang.String

DEFAULT_WAITTIME The initial default wait time used in the sendReceive() method call and all receive() method calls.

Constructor Summary

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

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.lang.String	getDefaultWaittime() Returns the default wait time.
java.lang.String	getEnvironment() Returns the environment.
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	setAdjustReceiveLen(boolean adj) Enables or disables the automatic adjustment of the maximum receive length when an application issues receive calls.
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	setEnvironment(java.lang.String env) Sets the value of the environment field to the argument.
void	setLogicalBroker(java.lang.String logicalBroker) Resolves a logical Broker and changes the Broker object accordingly.
void	setLogicalBroker(java.lang.String logicalBroker, java.lang.String logicalSetName) Resolves a logical Broker and changes the Broker object accordingly.
protected void	setLogicalBroker(java.lang.String logicalBroker, java.lang.String serverAddress, java.lang.String logicalSetName) Resolves a logical Broker and changes the Broker object and server address accordingly.
void	setLogicalService(java.lang.String logicalService) Resolves a logical service and changes the Broker object and server address accordingly.
void	setLogicalService(java.lang.String logicalService, java.lang.String logicalSetName) Resolves a logical service and changes the Broker object and server address accordingly.
void	setMaxReceiveLen(int len) Sets the current maximum receive length.
java.lang.String	toString() Overrides the toString() method of Object.
boolean	useCodePage() If communicating with broker version 7.1.x and below check if a locale string is sent to the broker or not.
void	useCodePage(boolean b) Force to send a locale string if communicating with Broker version 7.1.x and below.

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), Description of WAIT values, 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.

getEnvironment

public final java.lang.String getEnvironment()

Returns the environment.

Returns:

The environment as a String.

See Also:

setEnvironment(java.lang.String)

setEnvironment

public final void setEnvironment(java.lang.String env)

Sets the value of the environment field to the argument.
The environment field provides information for an EntireX Broker translation routine. The environment field is transmitted on all send and receive calls to the Broker.
This value can be specified only at the BrokerService level.

Parameters:

env - The value of the Environment field. The maximum length is 32 characters.

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, Detailed description of WAIT values

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.

setAdjustReceiveLen

public final void setAdjustReceiveLen(boolean adj)

Enables or disables the automatic adjustment of the maximum receive length when an application issues receive calls.

Parameters:

adj - true to enable receive length adjustment, false to disable receive length adjustment.

Since:

EntireX 5.2.1

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.

useCodePage

public final void useCodePage(boolean b)

Force to send a locale string if communicating with Broker version 7.1.x and below. You cannot use a codepage other than the default encoding of the JVM.

If set conversion is enabled. The default code page configured for your Java Virtual Machine will be sent to the Broker as the LOCALE_STRING. To change the default, see the Java Virtual Machine documentation. On some implementations, it can be changed with the file.encoding property. See the documentation of Java Virtual Machine on Internationalization for the supported code pages.

If not set the used approach translation or conversion is determined by the configuration of your partner (client or server). See Broker's handling of conversion/translation within the EntireX Internationalization overview for more information. Determines the translation processing of the EntireX Broker. It is assumed that you have read the introductory document Internationalization with EntireX and are familiar with the various internationalization approaches.

Parameters:

b - true to enable conversion; false to use configuration of partner.

Since:

EntireX 5.2.1

useCodePage

public final boolean useCodePage()

If communicating with broker version 7.1.x and below check if a locale string is sent to the broker or not. It is assumed that you have read the introductory document Internationalization with EntireX and are familiar with the various internationalization approaches.

Returns:

true if conversion is enabled; false if conversion or translation is determined by the partner.

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), Description of WAIT values

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.

Parameters:

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

errorText - the error text.

Returns:

true if the reply is send and the Broker supports this call. false if the current conversation is canceled. 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()

setLogicalService

public final void setLogicalService(java.lang.String logicalService)
                             throws BrokerException

Resolves a logical service and changes the Broker object and server address accordingly. For a logical service the real service and the real Broker ID are retrieved from an LDAP server. 'DefaultSet' is used as the name of the set.

Parameters:

logicalService - the logical service.

Throws:

BrokerException - the BrokerException thrown by LocationTransparencyService

See Also:

setLogicalService(String, String)

setLogicalService

public final void setLogicalService(java.lang.String logicalService,
                                    java.lang.String logicalSetName)
                             throws BrokerException

Resolves a logical service and changes the Broker object and server address accordingly. For a logical service the real service and the real Broker ID using the name of the set are retrieved from an LDAP server.

Parameters:

logicalService - the logical service.

logicalSetName - the logical set name.

Throws:

BrokerException - the BrokerException thrown by LocationTransparencyService

See Also:

LocationTransparencyService

setLogicalBroker

public final void setLogicalBroker(java.lang.String logicalBroker)
                            throws BrokerException

Resolves a logical Broker and changes the Broker object accordingly. For a logical Broker the real Broker ID is retrieved from an LDAP server. 'DefaultSet' is used as the name of the set.

Parameters:

logicalBroker - the logical broker.

Throws:

BrokerException - the BrokerException thrown by LocationTransparencyService

See Also:

setLogicalBroker(String)

setLogicalBroker

public final void setLogicalBroker(java.lang.String logicalBroker,
                                   java.lang.String logicalSetName)
                            throws BrokerException

Resolves a logical Broker and changes the Broker object accordingly. For a logical Broker the real Broker ID using the name of the set is retrieved from an LDAP server.

Parameters:

logicalBroker - the logical Broker.

logicalSetName - the logical set name.

Throws:

BrokerException - the BrokerException thrown by LocationTransparencyService

See Also:

LocationTransparencyService

setLogicalBroker

protected final void setLogicalBroker(java.lang.String logicalBroker,
                                      java.lang.String serverAddress,
                                      java.lang.String logicalSetName)
                               throws BrokerException

Resolves a logical Broker and changes the Broker object and server address accordingly. For a logical Broker the real Broker ID using the name of the set is retrieved from an LDAP server.

Parameters:

logicalBroker - the logical Broker.

serverAddress - the server address.

logicalSetName - the logical set name.

Throws:

BrokerException - the BrokerException thrown by LocationTransparencyService

See Also:

LocationTransparencyService

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.

The encoding is always sent as the locale string to the Broker if you are communicating with a Broker version 7.2.x or above.

If you are communicating with a Broker version 7.1.x or below the encoding is sent as the locale string to the Broker after setting the locale string with this method or after calling useCodePage(true). Setting enc to null disables this and sends no character encoding name to the Broker. In this case, the default encoding of the JVM is used and the character encoding is not send to the Broker. Use setCharacterEncoding("LOCAL") to send the default encoding to the Broker. It is assumed that you have read the introductory document Internationalization with EntireX and are familiar with the various internationalization approaches.

Parameters:

enc - the name of the character encoding or LOCAL or null.

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