services/appc-dmaap-service/appc-event-listener-bundle/src/main/java/org/onap/appc/listener/Listener.java

   1 /*-
   2  * ============LICENSE_START=======================================================
   3  * ONAP : APPC
   4  * ================================================================================
   5  * Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
   6  * ================================================================================
   7  * Copyright (C) 2017 Amdocs
   8  * =============================================================================
   9  * Licensed under the Apache License, Version 2.0 (the "License");
  10  * you may not use this file except in compliance with the License.
  11  * You may obtain a copy of the License at
  12  *
  13  *      http://www.apache.org/licenses/LICENSE-2.0
  14  *
  15  * Unless required by applicable law or agreed to in writing, software
  16  * distributed under the License is distributed on an "AS IS" BASIS,
  17  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  18  * See the License for the specific language governing permissions and
  19  * limitations under the License.
  20  *
  21  * ============LICENSE_END=========================================================
  22  */
  23
  24 package org.onap.appc.listener;
  25
  26 /**
  27  * This interface defines a listener that subscribes to a DMaaP topic and continually polls for messages. The
  28  * listener does all operations in the run() method and long running operations should be created in a separate worker
  29  * thread.
  30  *
  31  */
  32 public interface Listener extends Runnable {
  33
  34     /**
  35      * Should start a continuous poll to get messages from the message bus only ending when stop() or stopNow() are
  36      * called.
  37      *
  38      * @see java.lang.Runnable#run()
  39      */
  40     @Override
  41     public void run();
  42
  43     /**
  44      * Signals the listener to stop accepting new messages to the queue and to cleanly finish processing all remaining
  45      * messages in the queue. This can take a significant amount of time to complete depending on the thread pool
  46      * characteristics. Similar to {@link #stopNow()}
  47      */
  48     public void stop();
  49
  50     /**
  51      * Signals the listener to stop accepting new messages to the queue and to destroy all remaining messages in the
  52      * queue. This will complete quicker than {@link #stop()} at the cost of discarded requests. Recovery of these
  53      * requests would have to be caught downstream. Similar to {@link #stop()}
  54      */
  55     public void stopNow();
  56
  57     /**
  58      * @return A string that shows various benchmarking data. Can be used by humans to tune the thread pool.
  59      */
  60     public String getBenchmark();
  61
  62     /**
  63      * @return The listener's id when requesting messages from DMaaP. Also known as the group id.
  64      */
  65     public String getListenerId();
  66
  67     /**
  68      * Sets the listener's id to use when requesting messages from DMaaP. Also known as the group id.
  69      *
  70      * @param idString
  71      *            The new listener id
  72      */
  73     public void setListenerId(String idString);
  74 }