appc-event-listener/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 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  * ECOMP is a trademark and service mark of AT&T Intellectual Property.
  22  * ============LICENSE_END=========================================================
  23  */
  24
  25 package org.onap.appc.listener;
  26
  27 /**
  28  * This interface defines a listener that subscribes to a DMaaP topic and continually polls for messages. The
  29  * listener does all operations in the run() method and long running operations should be created in a separate worker
  30  * thread.
  31  *
  32  */
  33 public interface Listener extends Runnable {
  34
  35     /**
  36      * Should start a continuous poll to get messages from the message bus only ending when stop() or stopNow() are
  37      * called.
  38      *
  39      * @see java.lang.Runnable#run()
  40      */
  41     @Override
  42     public void run();
  43
  44     /**
  45      * Signals the listener to stop accepting new messages to the queue and to cleanly finish processing all remaining
  46      * messages in the queue. This can take a significant amount of time to complete depending on the thread pool
  47      * characteristics. Similar to {@link #stopNow()}
  48      */
  49     public void stop();
  50
  51     /**
  52      * Signals the listener to stop accepting new messages to the queue and to destroy all remaining messages in the
  53      * queue. This will complete quicker than {@link #stop()} at the cost of discarded requests. Recovery of these
  54      * requests would have to be caught downstream. Similar to {@link #stop()}
  55      */
  56     public void stopNow();
  57
  58     /**
  59      * @return A string that shows various benchmarking data. Can be used by humans to tune the thread pool.
  60      */
  61     public String getBenchmark();
  62
  63     /**
  64      * @return The listener's id when requesting messages from DMaaP. Also known as the group id.
  65      */
  66     public String getListenerId();
  67
  68     /**
  69      * Sets the listener's id to use when requesting messages from DMaaP. Also known as the group id.
  70      *
  71      * @param idString
  72      *            The new listener id
  73      */
  74     public void setListenerId(String idString);
  75 }