Package com.softwareag.entirex.aci

Class BrokerService

java.lang.Object
com.softwareag.entirex.aci.BrokerService
Direct Known Subclasses:
RPCService
public class BrokerService extends 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 Details

    • DEFAULT_WAITTIME

      public static final 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:

  • Constructor Details

    • BrokerService

      public BrokerService(Broker broker, 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:
      IllegalArgumentException - Thrown if a parameter is invalid.
      Since:
      EntireX 5.2.1
      See Also:

    • BrokerService

      public BrokerService(Broker broker, String serverClass, String serverName, 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:
      IllegalArgumentException - Thrown if a parameter is invalid.
      See Also:

  • Method Details

    • getBroker

      public Broker getBroker()
      Returns the Broker object to which the service belongs.
      Returns:
      An instance of the Broker class.

    • toString

      public final String toString()
      Overrides the toString() method of Object.
      Overrides:
      toString in class Object
      Returns:
      The complete service address as a string in the form ServerClass/ServerName/ServiceName.

    • getServerName

      public final String getServerName()
      Returns the server name.
      Returns:
      The server name as a string.

    • getServerClass

      public final String getServerClass()
      Returns the server class.
      Returns:
      The server class as a string.

    • getServiceName

      public final String getServiceName()
      Returns the service name.
      Returns:
      The service name as a string.

    • getDefaultWaittime

      public final String getDefaultWaittime()
      Returns the default wait time.
      Returns:
      The default wait time as a String.
      Since:
      EntireX 5.2.1
      See Also:

    • setDefaultWaittime

      public final void setDefaultWaittime(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:

    • 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.
      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:

    • 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.
      IllegalArgumentException - Thrown if no message is specified.
      See Also:

    • 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:

    • sendReceive

      public final BrokerMessage sendReceive(BrokerMessage msg, 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.
      IllegalArgumentException - Thrown if no message is specified or parameter is invalid.
      See Also:

    • 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(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.
      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(String errorCode, 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.
      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:

    • getCharacterEncoding

      public String getCharacterEncoding()
      Gets the character encoding name or null.
      Returns:
      the current character encoding name.
      Since:
      7.1.1.24

    • setCharacterEncoding

      public void setCharacterEncoding(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

    • getCharset

      public Charset getCharset()
      Gets the Charset used for this service.
      Returns:
      the current Charset.
      Since:
      10.5