org.primefaces.push.EventBus Maven / Gradle / Ivy

Show more of this group Show more artifacts with this name
Show all versions of primefaces Show documentation

PrimeFaces is one of the most popular UI libraries in Java EE Ecosystem and widely used by software companies, world renowned brands, banks, financial institutions, insurance companies, universities and more.

There is a newer version: 14.0.0-RC3

Show newest version

/**
 * Copyright 2009-2018 PrimeTek.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.primefaces.push;


import java.util.concurrent.Future;
import java.util.concurrent.TimeUnit;

/**
 * A distributed lightweight event bus which can encompass multiple PushEndpoint instances.
 * The event bus implements publish / subscribe and point to point messaging.
 * Messages sent over the event bus can be of any type. 
 * For publish / subscribe, messages can be published to a Java class annotated with the
 * {@link org.primefaces.push.annotation.PushEndpoint#value}
 * using one of the method annotated with {@link org.atmosphere.handler.OnMessage}.
 * 
 * {@link org.primefaces.push.annotation.PushEndpoint} are registered against a path, defined using the
 * {@link org.primefaces.push.annotation.PushEndpoint#value}.
 * There can be multiple PushEndpoint registered against each path, and a particular PushEndpoint can be registered against multiple paths.
 * The event bus will route a sent message to all PushEndpoint which are registered against that path.
 * When sending a message, a {@link Reply} can be provided. If so, it will be called when the reply from the receiver has been completed.
 * Instances of EventBus are thread-safe.
 */
public interface EventBus {

    /**
     * Fire an object to all connected {@link RemoteEndpoint}
     *
     * @param o an Object
     * @return this
     */
    EventBus publish(Object o);

    /**
     * Fire an object to {@link RemoteEndpoint} that connected using the path value.
     *
     * @param path A String starting with '/'
     * @param o    an Object
     * @return this
     */
    EventBus publish(String path, Object o);

    /**
     * Fire an object to {@link RemoteEndpoint} that connected using the path value.
     *
     * @param path A String starting with '/'
     * @param o    an Object
     * @param r    an {@link Reply}
     * @return this
     */
    EventBus publish(String path, Object o, Reply r);

    /**
     * Schedule a period push operation.
     * @param path a channel of communication.
     * @param t a message
     * @param time the time
     * @param unit the {@link TimeUnit}
     * @param  The type of the message
     * @return a Future that can used to cancel the periodic push
     */
     Future schedule(String path, T t, int time, TimeUnit unit);

    public static interface Reply {

        /**
         * Invoked when the {@link org.primefaces.push.EventBus} delivered the message to all
         * {@link org.primefaces.push.annotation.PushEndpoint} that matches the path used to initiate the publish operation.
         */
        void completed(String path);

    }

}