Package com.softwareag.entirex.aci

Class 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 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 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.

    • 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.
        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()

      • getCharacterEncoding

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

      • 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

      • getCharset

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