BrokerService (EntireX Java ACI)

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.

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

Methods
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.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`	`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), 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
  - 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.
    
    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.
    
    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)
  - 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()
  - 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.
    
    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

Class BrokerService

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

DEFAULT_WAITTIME

Constructor Detail

BrokerService

BrokerService

Method Detail

getBroker

toString

getServerName

getServerClass

getServiceName

getEnvironment

setEnvironment

getDefaultWaittime

setDefaultWaittime

getMaxReceiveLen

setMaxReceiveLen

setAdjustReceiveLen

isGeneric

useCodePage

useCodePage

register

registerAttach

deregister

deregisterImmediate

send

sendReceive

sendReceive

receive

receive

receiveOld

receiveAny

replyError

endallConversations

cancelallConversations

receiveAttachInfo

setCharacterEncoding

getCharacterEncoding