src/main/java/org/onap/dmaap/mr/client/MRTopicManager.java

   1 /*******************************************************************************
   2  *  ============LICENSE_START=======================================================
   3  *  org.onap.dmaap
   4  *  ================================================================================
   5  *  Copyright © 2017 AT&T Intellectual Property. All rights reserved.
   6  *  ================================================================================
   7  *  Modifications Copyright © 2021 Orange.
   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  *        http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *  Unless required by applicable law or agreed to in writing, software
  15  *  distributed under the License is distributed on an "AS IS" BASIS,
  16  *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  17  *  See the License for the specific language governing permissions and
  18  *  limitations under the License.
  19  *  ============LICENSE_END=========================================================
  20  *
  21  *  ECOMP is a trademark and service mark of AT&T Intellectual Property.
  22  *
  23  *******************************************************************************/
  24
  25 package org.onap.dmaap.mr.client;
  26
  27 import com.att.nsa.apiClient.http.HttpException;
  28 import com.att.nsa.apiClient.http.HttpObjectNotFoundException;
  29
  30 import java.io.IOException;
  31 import java.util.Set;
  32
  33
  34 /**
  35  * A client for working with topic metadata.
  36  *
  37  * @author author
  38  */
  39 public interface MRTopicManager extends MRClient {
  40     /**
  41      * Get the topics available in the cluster.
  42      *
  43      * @return a set of topic names
  44      * @throws IOException
  45      */
  46     Set<String> getTopics() throws IOException;
  47
  48     /**
  49      * Information about a topic.
  50      */
  51     interface TopicInfo {
  52         /**
  53          * Get the owner of the topic.
  54          *
  55          * @return the owner, or null if no entry
  56          */
  57         String getOwner();
  58
  59         /**
  60          * Get the description for this topic.
  61          *
  62          * @return the description, or null if no entry
  63          */
  64         String getDescription();
  65
  66         /**
  67          * Get the set of allowed producers (as API keys) on this topic.
  68          *
  69          * @return the set of allowed producers, null of no ACL exists/enabled
  70          */
  71         Set<String> getAllowedProducers();
  72
  73         /**
  74          * Get the set of allowed consumers (as API keys) on this topic.
  75          *
  76          * @return the set of allowed consumers, null of no ACL exists/enabled
  77          */
  78         Set<String> getAllowedConsumers();
  79     }
  80
  81     /**
  82      * Get information about a topic.
  83      *
  84      * @param topic
  85      * @return topic information
  86      * @throws IOException
  87      * @throws HttpObjectNotFoundException
  88      */
  89     TopicInfo getTopicMetadata(String topic) throws HttpObjectNotFoundException, IOException;
  90
  91     /**
  92      * Create a new topic.
  93      *
  94      * @param topicName
  95      * @param topicDescription
  96      * @param partitionCount
  97      * @param replicationCount
  98      * @throws HttpException
  99      * @throws IOException
 100      */
 101     void createTopic(String topicName, String topicDescription, int partitionCount, int replicationCount) throws HttpException, IOException;
 102
 103     /**
 104      * Delete the topic. This call must be authenticated and the API key listed as owner on the topic.
 105      * NOTE: The MR (UEB) API server does not support topic deletion at this time (mid 2015)
 106      *
 107      * @param topic
 108      * @throws HttpException
 109      * @throws IOException
 110      * @deprecated If/when the Kafka system supports topic delete, or the implementation changes, this will be restored.
 111      */
 112     @Deprecated
 113     void deleteTopic(String topic) throws HttpException, IOException;
 114
 115     /**
 116      * Can any client produce events into this topic without authentication?
 117      *
 118      * @param topic
 119      * @return true if the topic is open for producing
 120      * @throws IOException
 121      * @throws HttpObjectNotFoundException
 122      */
 123     boolean isOpenForProducing(String topic) throws HttpObjectNotFoundException, IOException;
 124
 125     /**
 126      * Get the set of allowed producers. If the topic is open, the result is null.
 127      *
 128      * @param topic
 129      * @return a set of allowed producers or null
 130      * @throws IOException
 131      * @throws HttpObjectNotFoundException
 132      */
 133     Set<String> getAllowedProducers(String topic) throws HttpObjectNotFoundException, IOException;
 134
 135     /**
 136      * Allow the given API key to produce messages on the given topic. The caller must
 137      * own this topic.
 138      *
 139      * @param topic
 140      * @param apiKey
 141      * @throws HttpException
 142      * @throws HttpObjectNotFoundException
 143      * @throws IOException
 144      */
 145     void allowProducer(String topic, String apiKey) throws HttpObjectNotFoundException, HttpException, IOException;
 146
 147     /**
 148      * Revoke the given API key's authorization to produce messages on the given topic.
 149      * The caller must own this topic.
 150      *
 151      * @param topic
 152      * @param apiKey
 153      * @throws HttpException
 154      * @throws IOException
 155      */
 156     void revokeProducer(String topic, String apiKey) throws HttpException, IOException;
 157
 158     /**
 159      * Can any client consume events from this topic without authentication?
 160      *
 161      * @param topic
 162      * @return true if the topic is open for consuming
 163      * @throws IOException
 164      * @throws HttpObjectNotFoundException
 165      */
 166     boolean isOpenForConsuming(String topic) throws HttpObjectNotFoundException, IOException;
 167
 168     /**
 169      * Get the set of allowed consumers. If the topic is open, the result is null.
 170      *
 171      * @param topic
 172      * @return a set of allowed consumers or null
 173      * @throws IOException
 174      * @throws HttpObjectNotFoundException
 175      */
 176     Set<String> getAllowedConsumers(String topic) throws HttpObjectNotFoundException, IOException;
 177
 178     /**
 179      * Allow the given API key to consume messages on the given topic. The caller must
 180      * own this topic.
 181      *
 182      * @param topic
 183      * @param apiKey
 184      * @throws HttpException
 185      * @throws HttpObjectNotFoundException
 186      * @throws IOException
 187      */
 188     void allowConsumer(String topic, String apiKey) throws HttpObjectNotFoundException, HttpException, IOException;
 189
 190     /**
 191      * Revoke the given API key's authorization to consume messages on the given topic.
 192      * The caller must own this topic.
 193      *
 194      * @param topic
 195      * @param apiKey
 196      * @throws HttpException
 197      * @throws IOException
 198      */
 199     void revokeConsumer(String topic, String apiKey) throws HttpException, IOException;
 200 }
 201