Menu
pushmode

Class PushServer

PushMode » API Reference » pushmode



  • public class PushServer
    extends Object
    Listens on a port and routes requests to pages (instances of PushPage). PushServer is an entry point to all PushMode functionality.
    PushServer is not a fully featured web server. It is a minimal application server. PushServer serves only HTML pages over HTTP/1.1 from single IP:port endpoint and streams their updates over HTTP/1.1 long-poll or plain websocket. You can get advanced web server features (virtual hosts, static files, TLS, HTTP2, compression, redirects, error pages, ...) by running generic web server (nginx, Apache) in front of PushMode. Additional server features like logging, configuration, monitoring, message queues and database access are provided by 3rd party libraries and cloud services. You can however use the FileServer during development.
    Thread-safety:
    Operations on PushServer are synchronized. It is safe to call them from multiple threads. There can be multiple PushServer instances in the same process as far as they listen on different ports or IPs.
    Lifecycle:
    PushServer has no daemon/service functionality. It is embedded as a library in a command-line application, which can be turned into a server by wrapping it with standard process management tools like supervisord or docker. During development, PushMode applications can be more easily restarted using ShutdownListener.
    • Method Detail

      • login

        public static PushServer login(String key)
        Creates new instance of PushServer and logs into PushMode cloud.
        Parameters:
        key - API key for logging into PushMode cloud. Currently just the beta key.
        Returns:
        this
      • listen

        public PushServer listen(InetAddress ip,
                                 int port)
        Changes listening IP address and port. Default port is 8080 and default IP address is localhost (as returned by InetAddress.getLoopbackAddress()).
        Parameters:
        ip - IP address where PushServer should be listening.
        port - TCP port where PushServer should be listening.
        Returns:
        this
        See Also:
        listen(int)
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only before the server is started.
      • listen

        public PushServer listen(int port)
        Changes listening port. Default is 8080. This method also resets IP address to the default (localhost as returned by InetAddress.getLoopbackAddress()).
        Parameters:
        port - TCP port where PushServer should be listening.
        Returns:
        this
        See Also:
        listen(InetAddress, int)
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only before the server is started.
      • map

        public PushServer map(String path,
                              Supplier<PushPage> supplier)
        Maps an exact path to a PushPage factory. Path /example will match /example but not /example/ nor /example2. Path /example/ will match /example/ but not /example/item nor /example/subdir/. Exact path mapping has priority over subtree(String, Supplier) mapping.
        Parameters:
        path - URL path to map. It must start with '/' and it must not contain any wildcards. Paths ending with '/' will map directory itself but not its contents.
        supplier - PushPage factory that creates the page, e.g. MyPage::new.
        Returns:
        this
        See Also:
        subtree(String, Supplier)
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only before the server is started.
      • subtree

        public PushServer subtree(String path,
                                  Supplier<PushPage> supplier)
        Maps whole URL subtree to a PushPage factory. Path /example/ will match /example/ as well as /example/item and /example/subdir/. If there are multiple subtree matches, the longer one wins, e.g. /example/subdir/ mapping wins over /example/ mapping. It is possible to create a fallback page by mapping whole root subtree (/) to the fallback page. Subtree mappings have lower priority than exact map(String, Supplier) mappings.
        Parameters:
        path - Directory prefix to map. It must start and end with '/' and it must not contain any wildcards.
        supplier - PushPage factory that creates the page, e.g. MyPage::new. You can call PageRequest.pending() within the factory to dynamically choose PushPage subclass based on URL or other request properties. If the PushPage factory returns null, PushServer will respond with 404 response to the request without trying any other mappings.
        Returns:
        this
        See Also:
        map(String, Supplier)
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only before the server is started.
      • start

        public PushServer start()
        Starts the server. When this method completes, PushServer is ready to serve requests.
        Returns:
        this
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only if the server has not been started yet. It will transition the server into started state. PushServer cannot be started and stopped multiple times.
      • stop

        public PushServer stop()
        Begins shutdown of the server. This method doesn't have immediate effect. Call join() to wait for shutdown to complete. Repeated calls have no effect.
        Returns:
        this
        Thread-safety:
        This method can be safely called from any thread.
        Lifecycle:
        This method can be called only after the server has been started. It will cause asynchronous transition to stopped state.
      • join

        public PushServer join()
        Waits for the server to stop. This method will block until the server shuts down. This method on its own doesn't cause the server to stop. Call stop() to trigger server shutdown. Calling this method on already stopped server has no effect.
        Returns:
        this
        Thread-safety:
        This method can be safely called from any thread. It can be simultaneously called from multiple threads. It will block current thread until the server stops. It does not interfere with method calls from other threads, i.e. it does not hold any locks.
        Lifecycle:
        This method can be called any time after the server is started, even before stop() is called. It will return only after the server is fully stopped.
      • run

        public PushServer run()
        Starts the server and blocks the current thread until the server stops. Calling this method is equivalent to calling start() followed by join(). Refer to those methods for details of their behavior. You can call stop() from another thread to stop the server.
        Returns:
        this
        See Also:
        start(), join()
      • version

        public static String version()
        PushMode version.
        Returns:
        Version of the currently running PushMode library.
      • production

        public boolean production()
        Indicates whether this is production server (as opposed to development server). Value of this property depends on the kind of server key passed to login(String). Various parts of PushMode framework make use of this property to optimize the server for production or development use.
        Returns:
        True if this is production server according to the server key.