001/*******************************************************************************
002 * Copyright (c) 2017 Red Hat Inc and others.
003 *
004 * All rights reserved. This program and the accompanying materials
005 * are made available under the terms of the Eclipse Public License v1.0
006 * which accompanies this distribution, and is available at
007 * http://www.eclipse.org/legal/epl-v10.html
008 *
009 * Contributors:
010 *     Red Hat Inc - initial API and implementation
011 *******************************************************************************/
012package org.eclipse.kapua.gateway.client;
013
014/**
015 * An interface for control data
016 * <p>
017 * An instance of this is bound to a topic and can be looked up by a call
018 * to {@link Application#data(Topic)}.
019 * </p>
020 */
021public interface Data extends Sender<Exception> {
022
023    /**
024     * Receive messages on this data topic
025     * <p>
026     * Subscriptions will automatically be re-established after a connection loss.
027     * </p>
028     * 
029     * @param handler
030     *            the handler which should process received messages
031     * @throws Exception
032     *             if anything goes wrong on the subscription process
033     */
034    public default void subscribe(final MessageHandler handler) throws Exception {
035        subscribe(handler, Errors::ignore);
036    }
037
038    /**
039     * Receive messages and handle reception errors on this data topic
040     * <p>
041     * Subscriptions will automatically be re-established after a connection loss.
042     * </p>
043     * 
044     * @param handler
045     *            the handler which should process received messages
046     * @param errorHandler
047     *            the handler which should process received messages which got received
048     *            but could not be properly parsed
049     * @throws Exception
050     *             if anything goes wrong on the subscription process
051     */
052    public void subscribe(MessageHandler handler, ErrorHandler<? extends Throwable> errorHandler) throws Exception;
053}