Class RPCService

  • Direct Known Subclasses:
    XMLRPCService

    public abstract class RPCService
    extends BrokerService
    This abstract subclass of BrokerService represents a Broker service used by EntireX RPC. The client stub and server stub generated by the Java Wrapper are subclasses of RPCService.
    You should not call the methods of the superclass BrokerService directly.
    Since:
    EntireX 5.2.1
    • Field Detail

      • RELIABLE_AUTO_COMMIT

        public static final int RELIABLE_AUTO_COMMIT
        RELIABLE_AUTO_COMMIT = 1
        See Also:
        Constant Field Values
      • RELIABLE_CLIENT_COMMIT

        public static final int RELIABLE_CLIENT_COMMIT
        RELIABLE_CLIENT_COMMIT = 2
        See Also:
        Constant Field Values
    • Method Detail

      • setRPCUserId

        public final void setRPCUserId​(java.lang.String userId1)
        Changes the user ID used for an RPC call. Default is the user ID specified in the Broker constructor. An empty user ID is ignored.
        Parameters:
        userId1 - The new user ID.
        Since:
        5.2.1.7
      • getRPCUserId

        public final java.lang.String getRPCUserId()
        Returns the user ID which is used by the RPCs.
        Returns:
        user ID as string.
        Since:
        5.2.1.7
      • setRPCPassword

        public final void setRPCPassword​(java.lang.String password1)
        Changes the password used for an RPC. Default is the password specified in the Broker logon method. At the moment this is only used by Natural RPC servers running with Natural Security.
        Parameters:
        password1 - The new Password.
        Since:
        5.2.1.7
      • getRPCPassword

        public final java.lang.String getRPCPassword()
        Gets the RPC password (used with NATURAL logon).
        Returns:
        the RPC password.
      • setBroker

        public final void setBroker​(Broker broker)
                             throws BrokerException
        Dynamically assigns the instance of a Broker object. The method cannot be called during a conversational RPC sequence. Can be used by Java Wrapper Customization classes.
        Parameters:
        broker - A Broker instance.
        Throws:
        BrokerException - A BrokerException.
        Since:
        5.3.1.2
      • setServerAddress

        public final void setServerAddress​(java.lang.String serverAddress)
                                    throws BrokerException
        Dynamically assigns the server address. The method cannot be called during a conversational RPC sequence. Can be used by Java Wrapper Customization classes.
        Parameters:
        serverAddress - The server address (class/name/service).
        Throws:
        BrokerException - if called in a conversational RPC sequence.
        Since:
        5.3.1.2
      • setLibraryName

        public final void setLibraryName​(java.lang.String libName)
        Changes the library name used by the RPC.
        Parameters:
        libName - The new library name (maximum 8 characters).
      • getLibraryName

        public java.lang.String getLibraryName()
        Returns the current value of the library name used by the RPC.
        Returns:
        The current library name as a string.
      • getProgramName

        public java.lang.String getProgramName()
        Returns the current value of the RPC subprogram name.
        Returns:
        The current subprogram name as a String.
      • setNaturalLogon

        public final void setNaturalLogon​(boolean logon)
        Enables or disables logon to Natural Security for Natural RPC servers.
        Parameters:
        logon - true to enable, false to disable.
      • getNaturalLogon

        public final boolean getNaturalLogon()
        Returns the current setting for logon to Natural Security for Natural RPC servers.
        Returns:
        true if enabled, false if disabled.
      • setConversation

        public final void setConversation​(Conversation conversation)
        Enables conversational RPC. All RPCs going through this instance of the RPCService object will use the Conversation object passed as parameter.

        The same instance of a Conversation object can be passed to different instances of an RPCService object. They will all run in the same conversation.

        Parameters:
        conversation - A non-null Conversation object.
        Throws:
        java.lang.IllegalArgumentException - Thrown if no conversation is specified.
        java.lang.IllegalStateException - if this service is already used for reliable RPC.
      • getConversation

        protected final Conversation getConversation()
        Returns the Conversation object.
        Returns:
        Conversation object or null;
      • closeConversation

        public final void closeConversation()
                                     throws BrokerException
        Closes the running RPC conversation. The RPC server receives a "backout" notification.
        Throws:
        BrokerException - A BrokerException.
      • closeConversationCommit

        public final void closeConversationCommit()
                                           throws BrokerException
        Closes the running RPC conversation. The RPC server receives a "commit" notification.
        Throws:
        BrokerException - A BrokerException.
      • reliableCommit

        public final void reliableCommit()
                                  throws BrokerException
        Commit a transaction (unit of work) for reliable RPC.
        Throws:
        BrokerException - if the broker call to commit the messages fails.
        Since:
        8.0
      • reliableRollback

        public final void reliableRollback()
                                    throws BrokerException
        Roll back a transaction (unit of work) for reliable RPC.
        Throws:
        BrokerException - if the broker call to commit the messages fails.
        Since:
        8.0
      • getStatusOfMessage

        public final java.lang.String getStatusOfMessage​(java.lang.String messageID)
                                                  throws BrokerException
        Gets the status of the message identified by the message id for reliable RPC. The message id is the UnitofWork id. Due to Broker settings the status may be not available after processing the message.
        Parameters:
        messageID - the message id obtained by a previous call of getMessageID().
        Returns:
        the status of the message.
        Throws:
        BrokerException - if the Broker call fails.
        Since:
        8.0
      • onEnter

        protected void onEnter​(java.lang.String progname)
                        throws BrokerException
        User exit method called at the beginning of a generated method. This method has a default implementation and can be overwritten in the Java Wrapper Customization class.
        Parameters:
        progname - The RPC program name.
        Throws:
        BrokerException - A BrokerException.
        Since:
        5.3.1.2
      • onLeave

        protected void onLeave​(java.lang.String progname,
                               int sendLength,
                               int receiveLength)
                        throws BrokerException
        User exit method called at the end of a generated method. This method is only called when no exception is thrown. This method has a default implementation and can be overwritten in the Java Wrapper Customization class.
        Parameters:
        progname - The RPC program name.
        sendLength - length of send buffer
        receiveLength - length of receive buffer
        Throws:
        BrokerException - A BrokerException.
        Since:
        5.3.1.2
      • onException

        protected void onException​(java.lang.String progname,
                                   BrokerException exception)
                            throws BrokerException
        User exit method called when an exception which is an instance of BrokerException is thrown in the generated method. After calling this method the exception is thrown again. There is no need to throw the exception in the implementation of this method. This method has a default implementation and can be overriden in the Java Wrapper Customization class.
        Parameters:
        progname - The RPC program name.
        exception - reference to the exception, which is thrown in the generated method.
        Throws:
        BrokerException - A BrokerException.
        Since:
        5.3.1.2
      • onRetry

        protected boolean onRetry​(java.lang.String progname,
                                  BrokerException exception)
                           throws BrokerException
        User exit method called when an exception which is an instance of BrokerException is thrown in the generated method. This method is only called when the exception is thrown during the processing of the RPC. If this method returns false, the exception will be thrown again and the onException method is called. If this method returns true, the RPC will be executed once again. If the second RPC fails, onException will be called immediately. This method has a default implementation and can be overridden in the Java Wrapper Customization class.
        Parameters:
        progname - The RPC program name.
        exception - reference to the exception which is thrown in the generated method.
        Returns:
        false as a default implementation.
        Throws:
        BrokerException - A BrokerException.
        Since:
        5.3.1.2
      • ping

        public java.lang.String ping()
                              throws BrokerException
        Sends an RPC PING command to the service and returns the response string.
        Returns:
        the response string to the PING command.
        Throws:
        BrokerException - if a Broker error occurs.
        Since:
        7.1.1.24
      • setReliable

        public final void setReliable​(int mode)
        Sets reliable RPC mode. Allowed values are RELIABLE_OFF, RELIABLE_AUTO_COMMIT, RELIABLE_CLIENT_COMMIT.
        Parameters:
        mode - the reliable RPC mode to set
        Throws:
        java.lang.IllegalStateException - if this service is already used for reliable RPC.
        Since:
        8.0
      • getMessageIDOfRequest

        public java.lang.String getMessageIDOfRequest()
        Gets the messageID of the RPC request.
        Returns:
        the messageID of the RPC request.
        Since:
        10.5
      • getCorrelationIDOfReply

        public java.lang.String getCorrelationIDOfReply()
        Gets the messageID of the RPC response.
        Returns:
        the messageID of the RPC response.
        Since:
        10.5