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