nxt.http

## Class EventRegister

- java.lang.Object
- - nxt.http.APIServlet.APIRequestHandler
  - - nxt.http.EventRegister

-     public class EventRegister
      extends APIServlet.APIRequestHandler

  The EventRegister API will create an event listener and register one or more server events. The 'add' and 'remove' parameters must be omitted or must both be false in order to create a new event listener.

  After calling EventRegister, the application needs to call the EventWait API to wait for one of the registered events to occur. The events will remain registered so successive calls to EventWait can be made without another call to EventRegister.

  When the event listener is no longer needed, the application should call EventRegister with an empty event list and 'remove=true'. An outstanding event wait will be completed and the event listener will be canceled.

  An existing event list can be modified by calling EventRegister with either 'add=true' or 'remove=true'. The current event list will be replaced if both parameters are omitted or are false.

  Event registration will be canceled if the application does not issue an EventWait before the time interval specified by nxt.apiEventTimeout expires. The timer is reset each time an EventWait is processed.

  An application cannot register events if the maximum number of event users specified by nxt.apiMaxEventUsers has been reached or if the maximum number of user registrations specified by nxt.api.MaxUserEventRegistrations has been reached.

  Request parameters:

  - token - Registration token. Omit this parameter or set it to 0 to create a new event registration. Set this parameter to the value returned by a previous event registration to modify an existing registration.
  - event - Event name. The 'event' parameter can be repeated to specify multiple events. All events will be included if the 'event' parameter is not specified.
  - add - Specify 'true' to add the events to an existing event list. Ignored if creating a new event registration.
  - remove - Specify 'true' to remove the events from an existing event list. Ignored if creating a new event registration.

  Response parameters:

  - registered - Set to 'true' if the events were processed.
  - token - Set to the event registration token. This token must be used to wait for events and to modify or cancel the registration.

  Error Response parameters:

  - errorCode - API error code
  - errorDescription - API error description

  Event names:

  - Block.BLOCK_GENERATED
  - Block.BLOCK_POPPED
  - Block.BLOCK_PUSHED
  - Ledger.ADD_ENTRY.account - Monitor changes to the specified account. 'account' may be the numeric identifier or the Reed-Solomon identifier of the account to monitor for updates. All accounts will be monitored if no account is specified. Specifying an account identifier of 0 is the same as not specifying an account.
  - Peer.ADD_ACTIVE_PEER
  - Peer.ADD_PEER
  - Peer.BLACKLIST
  - Peer.CHANGE_ACTIVE_PEER
  - Peer.CHANGE_ANNOUNCED_ADDRESS
  - Peer.CHANGE_SERVICES
  - Peer.REMOVE_PEER
  - Peer.UNBLACKLIST
  - Transaction.ADDED_CONFIRMED_TRANSACTIONS.account (omit account to monitor all accounts)
  - Transaction.ADDED_UNCONFIRMED_TRANSACTIONS.account (omit account to monitor all accounts)
  - Transaction.REJECT_PHASED_TRANSACTION.account (omit account to monitor all accounts)
  - Transaction.RELEASE_PHASED_TRANSACTION.account (omit account to monitor all accounts)
  - Transaction.REMOVED_UNCONFIRMED_TRANSACTIONS.account (omit account to monitor all accounts)

- - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `allowRequiredBlockParameters()`
    `protected boolean` | `isChainSpecific()`
    `protected org.json.simple.JSONStreamAware` | `processRequest(javax.servlet.http.HttpServletRequest req)` Process the EventRegister API request
    `protected boolean` | `requirePost()`

    - ### Methods inherited from class nxt.http.APIServlet.APIRequestHandler

      `getAPITags, getFileParameter, getParameters, isIgnisOnly, isPassword, isTextArea, processRequest, requireBlockchain, requireFullClient, requirePassword, startDbTransaction`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### processRequest

          protected org.json.simple.JSONStreamAware processRequest(javax.servlet.http.HttpServletRequest req)
                                                            throws ParameterException

      Process the EventRegister API request
      Specified by:
        `processRequest` in class `APIServlet.APIRequestHandler`
      Parameters:
        `req` - API request
      Returns:
        API response
      Throws:
        `ParameterException` - Invalid parameter specified

    - #### requirePost

          protected final boolean requirePost()

      Overrides:
        `requirePost` in class `APIServlet.APIRequestHandler`

    - #### allowRequiredBlockParameters

          protected boolean allowRequiredBlockParameters()

      Overrides:
        `allowRequiredBlockParameters` in class `APIServlet.APIRequestHandler`

    - #### isChainSpecific

          protected boolean isChainSpecific()

      Overrides:
        `isChainSpecific` in class `APIServlet.APIRequestHandler`