Class AsteriskHandler

  • All Implemented Interfaces:
    Handler, TemplateInterface

    public class AsteriskHandler
    extends Template
    implements Handler
    Connect to asterisk manager api. There is one connection per server. This is used both to issue Commands to Asterisk via the manager interface, and to register for, and receive asynchronous event notifications.

    Usage:

     <register queue=xxx key=xxx pattern=xxx [context=xxx server=xxx]>
      - register interest in a manager event (or events).  All generated events
        will be available with <dequeue name=xxx ...>, where the "name"
        parameter of the <dequeue> matches the "queue" parameter of
        <register>.
     <unregister queue=xxx key=xxx>
      - unregister interest in a previously registered event.
     <enqueue name="queue" from="my-q" ...>
      - Send an command to the manager interface. "queue" is the name
        specified in the handler "queue" parameter.  The enqueue'd data
        must have an "action" key.  The result of the command is obtained by:
        <dequeue name="my-q" ...>  where "my-q" is the "from" attribute of
        the corrosponding <enqueue>
     <amicommand server=xxx action=xxx ...>
      - A syncronous version of the <enqueue> ... <dequeue> above.
        See below for details.
     

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  AsteriskHandler.AmiStringMap
      This class is built on top of the StringMap class and adds methods for reading Asterisk ManagerInterface replies.
      static class  AsteriskHandler.EventItem
      Keep track of an event listener entry.
      static class  AsteriskHandler.Events
      Class to manage the set of events.
    • Field Summary

    • Constructor Summary

      Constructors 
      Constructor Description
      AsteriskHandler()  
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static void addEvent​(java.lang.String queue, java.lang.String key, java.lang.String exp, java.lang.String context, java.lang.String serverName)
      Java access to adding event registrations.
      boolean init​(Server server, java.lang.String prefix)
      Remember the host, port, id, and password for an asterisk manager connection.
      static int removeEvents​(java.lang.String queue, java.lang.String key, java.lang.String exp)
      java access to removing event registrations.
      boolean respond​(Request request)
      The handler only registers * servers.
      void tag_amicommand​(RewriteContext hr)
      Issue a synchronous command to the Asterisk AMI interface.
      void tag_asterisk​(RewriteContext hr)
      This only emits diagnostic information to stdout.
      void tag_register​(RewriteContext hr)
      Register an event.
      void tag_unregister​(RewriteContext hr)
      Unregister an event (or events).
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • AsteriskHandler

        public AsteriskHandler()
    • Method Detail

      • init

        public boolean init​(Server server,
                            java.lang.String prefix)
        Remember the host, port, id, and password for an asterisk manager connection. We don't require that the asterisk server actually be running at server startup time. We will try hard to reconnect to the server if it goes away.
        queue
        The name of the Q to send manager commands to using the <enqueue name="queue" ...>. If not specifies, the "host:port" combination is used.
        server
        The server:port to use to contact the asterisk server
        userid, password
        The Manager credentials
        debug=true|false
        turn on more diagnostics on the console, depending on the current server logging level. at "3", keep alives are logged, at "4", all events are logged, and at "5" even more stuff is logged.
        keepalive=n
        If set, this handler will issue a keep-alive every "n" seconds to the Asterisk Server. If the keep-alive fails, a new connection will be attempted with the Asterisk server.
        retry=n
        Set the number of seconds to wait before retrying a broken connection to an asterisk server (defaults to 10).
        To communicate with multiple asterisk servers, each should have their own handler instance. Servers are distinguished when sending commands to them via the "queue" parameter, which should be different for each server. Alternately, the <amicommand> server parameter (which is the same as the server queue name) may be used.

        When using multiple servers, only one of the server handler configurations should be listed as a template (there can only be one template instance for a given entity) which server doesn't matter, as events get registered for all servers (the "server" attribute of the response determines where it came from). As above, commands to a server are distinquished with either the "queue" or "server" attributes, depending on whether the command Qs are used directly, or the <amicommand> template is used.

        To Do
        Figure out where to send unregistered events, such as "reload".

        Specified by:
        init in interface Handler
        Parameters:
        server - The HTTP server that created this Handler. Typical Handlers will use Server.props to obtain run-time configuration information.
        prefix - The handlers name. The string this Handler may prepend to all of the keys that it uses to extract configuration information from Server.props. This is set (by the Server and ChainHandler) to help avoid configuration parameter namespace collisions.
        Returns:
        true if this Handler initialized successfully, false otherwise. If false is returned, this Handler should not be used.
      • respond

        public boolean respond​(Request request)
                        throws java.io.IOException
        The handler only registers * servers. No requests are handled. Use <register> in a template instead.
        Specified by:
        respond in interface Handler
        Parameters:
        request - The Request object that represents the HTTP request.
        Returns:
        true if the request was handled. A request was handled if a response was supplied to the client, typically by calling Request.sendResponse() or Request.sendError.
        Throws:
        java.io.IOException - if there was an I/O error while sending the response to the client. Typically, in that case, the Server will (try to) send an error message to the client and then close the client's connection.

        The IOException should not be used to silently ignore problems such as being unable to access some server-side resource (for example getting a FileNotFoundException due to not being able to open a file). In that case, the Handler's duty is to turn that IOException into a HTTP response indicating, in this case, that a file could not be found.

      • tag_asterisk

        public void tag_asterisk​(RewriteContext hr)
        This only emits diagnostic information to stdout.
      • tag_amicommand

        public void tag_amicommand​(RewriteContext hr)
        Issue a synchronous command to the Asterisk AMI interface. This is a convenience for using <enqueue> and <dequeue> directly.

        Attributes:

        server
        The Asterisk server's Q (required).
        action:
        The action to perform.
        variable=value
        one of the variables needed by the action. (There is a fixed list, See the manager docs for more detail).
        timeout
        The max time to wait for a response
        prepend
        What to prepend all the results too.
      • tag_register

        public void tag_register​(RewriteContext hr)
        Register an event.
        <register queue=xxx key=xxx exp=xxx [context=xxx server=xxx]>
          queue:  The Q name to send the results to.
          key:    The manager response key to match on.  Use "*" for all keys.
          exp:  A regular expression that matches a key value
          context: If specified, only events with this context are considered. 
          server: If specified, only events from this server are considered. 
                The server matches the "Server" item in the event, and is the server
          name, followed by a ":", then the port number (e.g. pbx.com:5038).
         
      • addEvent

        public static void addEvent​(java.lang.String queue,
                                    java.lang.String key,
                                    java.lang.String exp,
                                    java.lang.String context,
                                    java.lang.String serverName)
        Java access to adding event registrations.
      • tag_unregister

        public void tag_unregister​(RewriteContext hr)
        Unregister an event (or events). Match on "queue", "exp" and "key"
      • removeEvents

        public static int removeEvents​(java.lang.String queue,
                                       java.lang.String key,
                                       java.lang.String exp)
        java access to removing event registrations.