You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pinot.apache.org by su...@apache.org on 2019/04/04 19:29:48 UTC
[incubator-pinot] branch master updated: Introduce interface
stability and audience annotations (#4063)
This is an automated email from the ASF dual-hosted git repository.
sunithabeeram pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-pinot.git
The following commit(s) were added to refs/heads/master by this push:
new 3a9625b Introduce interface stability and audience annotations (#4063)
3a9625b is described below
commit 3a9625bec5c5e986004f61246a80725b0c9bf4a3
Author: Sunitha Beeram <sb...@linkedin.com>
AuthorDate: Thu Apr 4 12:29:42 2019 -0700
Introduce interface stability and audience annotations (#4063)
* Introduce interface stability and audience annotations
* Address review comments
* Address review comments
* Address review comments
---
.../pinot/annotations/InterfaceAudience.java | 73 ++++++++++++++++++++++
.../pinot/annotations/InterfaceStability.java | 70 +++++++++++++++++++++
.../pinot/core/indexsegment/IndexSegment.java | 3 +-
.../pinot/core/realtime/stream/MessageBatch.java | 6 ++
.../realtime/stream/PartitionLevelConsumer.java | 4 ++
.../core/realtime/stream/StreamLevelConsumer.java | 4 ++
.../core/realtime/stream/StreamMessageDecoder.java | 4 ++
.../realtime/stream/StreamMetadataProvider.java | 4 ++
8 files changed, 167 insertions(+), 1 deletion(-)
diff --git a/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceAudience.java b/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceAudience.java
new file mode 100644
index 0000000..865bdf6
--- /dev/null
+++ b/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceAudience.java
@@ -0,0 +1,73 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pinot.annotations;
+
+import java.lang.annotation.Documented;
+
+
+/**
+ * Annotation to inform users of a package, class or method's intended audience.
+ *
+ * Currently the audience can be {@link org.apache.pinot.annotations.InterfaceAudience.Public},
+ * {@link org.apache.pinot.annotations.InterfaceAudience.LimitedPrivate} or
+ * {@link org.apache.pinot.annotations.InterfaceAudience.Private}. <br>
+ *
+ * <ul>
+ * <li>Public classes that are not marked with this annotation must be
+ * considered by default as {@link org.apache.pinot.annotations.InterfaceAudience.Private}.</li>
+ *
+ * <li>External application developers depending on Pinot must only use classes that are marked
+ * {@link org.apache.pinot.annotations.InterfaceAudience.Public}. Do not depend on classes without an
+ * explicit InterfaceAudience.Public annotation as these classes
+ * could be removed or change in incompatible ways.</li>
+ *
+ * <li> Methods may have a different annotation that it is more restrictive
+ * compared to the audience classification of the class. Example: A class
+ * might be {@link org.apache.pinot.annotations.InterfaceAudience.Public},
+ * but a method may be {@link org.apache.pinot.annotations.InterfaceAudience.LimitedPrivate}
+ * </li></ul>
+ *
+ * The annotation is borrowed from a similar Apache Hadoop annotation.
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
+public class InterfaceAudience {
+ /**
+ * Intended for use by any project or application.
+ */
+ @Documented
+ public @interface Public {};
+
+ /**
+ * Intended only for the project(s) specified in the annotation.
+ * Reserved for future use.
+ */
+ @Documented
+ public @interface LimitedPrivate {
+ String[] value();
+ };
+
+ /**
+ * Intended for use only within Pinot itself.
+ */
+ @Documented
+ public @interface Private {};
+
+ private InterfaceAudience() {} // Audience can't exist on its own
+}
\ No newline at end of file
diff --git a/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceStability.java b/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceStability.java
new file mode 100644
index 0000000..26eeda3
--- /dev/null
+++ b/pinot-common/src/main/java/org/apache/pinot/annotations/InterfaceStability.java
@@ -0,0 +1,70 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+package org.apache.pinot.annotations;
+import java.lang.annotation.Documented;
+
+/**
+ * Annotation to inform users of how much to rely on a particular package,
+ * class or method not changing over time. Currently the stability can be
+ * {@link org.apache.pinot.annotations.InterfaceStability.Stable},
+ * {@link org.apache.pinot.annotations.InterfaceStability.Evolving} or
+ * {@link org.apache.pinot.annotations.InterfaceStability.Unstable}. <br>
+ *
+ * <ul>
+ * <li>All classes that are annotated with {@link org.apache.pinot.annotations.InterfaceAudience.Public} must have
+ * InterfaceStability annotation. </li>
+ * <li>Classes that are {@link org.apache.pinot.annotations.InterfaceAudience.Private} are to be considered unstable
+ * unless a different InterfaceStability annotation states otherwise.</li>
+ * <li>Pinot contributors should NOT make incompatible changes to classes marked as stable.
+ * Some things to watch out for classes marked as stable:
+ * <ul>
+ * <li> Method(s) cannot be removed from classes/interfaces marked as stable during minor version releases.
+ * Deprecate the method(s) first and remove the method in a major release.</li>
+ * <li> Similar to earlier point, method signature cannot change.</li>
+ * <li> New methods cannot be added to interfaces without providing default implementation for minor version
+ * releases.</li></ul>
+ * </ul>
+ * </li>
+ * </ul>
+ *
+ * Note: the definitions are borrowed from a similar annotation from Apache Hadoop project.
+ */
+@InterfaceAudience.Public
+@InterfaceStability.Evolving
+public class InterfaceStability {
+ /**
+ * Can evolve while retaining compatibility for minor release boundaries.;
+ * can break compatibility only at major release (ie. at m.0).
+ */
+ @Documented
+ public @interface Stable {};
+
+ /**
+ * Evolving, but can break compatibility at minor release (i.e. m.x)
+ */
+ @Documented
+ public @interface Evolving {};
+
+ /**
+ * No guarantee is provided as to reliability or stability across any
+ * level of release granularity.
+ */
+ @Documented
+ public @interface Unstable {};
+}
\ No newline at end of file
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/indexsegment/IndexSegment.java b/pinot-core/src/main/java/org/apache/pinot/core/indexsegment/IndexSegment.java
index 19f9fdc..692b017 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/indexsegment/IndexSegment.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/indexsegment/IndexSegment.java
@@ -20,12 +20,13 @@ package org.apache.pinot.core.indexsegment;
import java.util.List;
import java.util.Set;
+import org.apache.pinot.annotations.InterfaceAudience;
import org.apache.pinot.common.segment.SegmentMetadata;
import org.apache.pinot.core.common.DataSource;
import org.apache.pinot.core.data.GenericRow;
import org.apache.pinot.core.startree.v2.StarTreeV2;
-
+@InterfaceAudience.Private
public interface IndexSegment {
/**
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/MessageBatch.java b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/MessageBatch.java
index 3ee6781..86c722b 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/MessageBatch.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/MessageBatch.java
@@ -18,11 +18,17 @@
*/
package org.apache.pinot.core.realtime.stream;
+import org.apache.pinot.annotations.InterfaceAudience;
+import org.apache.pinot.annotations.InterfaceStability;
+
+
/**
* Interface wrapping stream consumer. Throws IndexOutOfBoundsException when trying to access a message at an
* invalid index.
* @param <T>
*/
+@InterfaceAudience.Public
+@InterfaceStability.Stable
public interface MessageBatch<T> {
/**
*
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/PartitionLevelConsumer.java b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/PartitionLevelConsumer.java
index 631cf85..5741d3b 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/PartitionLevelConsumer.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/PartitionLevelConsumer.java
@@ -19,11 +19,15 @@
package org.apache.pinot.core.realtime.stream;
import java.io.Closeable;
+import org.apache.pinot.annotations.InterfaceAudience;
+import org.apache.pinot.annotations.InterfaceStability;
/**
* Interface for a consumer which fetches messages at the partition level of a stream, for given offsets
*/
+@InterfaceAudience.Public
+@InterfaceStability.Stable
public interface PartitionLevelConsumer extends Closeable {
/**
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamLevelConsumer.java b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamLevelConsumer.java
index b413571..fc8cc19 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamLevelConsumer.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamLevelConsumer.java
@@ -18,12 +18,16 @@
*/
package org.apache.pinot.core.realtime.stream;
+import org.apache.pinot.annotations.InterfaceAudience;
+import org.apache.pinot.annotations.InterfaceStability;
import org.apache.pinot.core.data.GenericRow;
/**
* Interface for a consumer that consumes at stream level and is unaware of any partitions of the stream
*/
+@InterfaceAudience.Public
+@InterfaceStability.Stable
public interface StreamLevelConsumer {
/**
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMessageDecoder.java b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMessageDecoder.java
index 44d667f..d95bb7f 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMessageDecoder.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMessageDecoder.java
@@ -19,6 +19,8 @@
package org.apache.pinot.core.realtime.stream;
import java.util.Map;
+import org.apache.pinot.annotations.InterfaceAudience;
+import org.apache.pinot.annotations.InterfaceStability;
import org.apache.pinot.common.data.Schema;
import org.apache.pinot.core.data.GenericRow;
@@ -27,6 +29,8 @@ import org.apache.pinot.core.data.GenericRow;
* Interface for a decoder of messages fetched from the stream
* @param <T>
*/
+@InterfaceAudience.Public
+@InterfaceStability.Stable
public interface StreamMessageDecoder<T> {
/**
diff --git a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMetadataProvider.java b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMetadataProvider.java
index 4e24b6b..e7e2a94 100644
--- a/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMetadataProvider.java
+++ b/pinot-core/src/main/java/org/apache/pinot/core/realtime/stream/StreamMetadataProvider.java
@@ -20,11 +20,15 @@ package org.apache.pinot.core.realtime.stream;
import java.io.Closeable;
import javax.annotation.Nonnull;
+import org.apache.pinot.annotations.InterfaceAudience;
+import org.apache.pinot.annotations.InterfaceStability;
/**
* Interface for provider of stream metadata such as partition count, partition offsets
*/
+@InterfaceAudience.Public
+@InterfaceStability.Stable
public interface StreamMetadataProvider extends Closeable {
/**
* Fetches the number of partitions for a topic given the stream configs
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@pinot.apache.org
For additional commands, e-mail: commits-help@pinot.apache.org