Added InterfaceStability class with stability annotations. Project: http://git-wip-us.apache.org/repos/asf/metamodel/repo Commit: http://git-wip-us.apache.org/repos/asf/metamodel/commit/b5291990 Tree: http://git-wip-us.apache.org/repos/asf/metamodel/tree/b5291990 Diff: http://git-wip-us.apache.org/repos/asf/metamodel/diff/b5291990
Branch: refs/heads/master Commit: b529199001e44a8174570298444e88cb5de6a182 Parents: cdb2b5b Author: Kasper Sørensen <i.am.kasper.soren...@gmail.com> Authored: Mon Jun 4 19:54:40 2018 -0700 Committer: Kasper Sørensen <i.am.kasper.soren...@gmail.com> Committed: Mon Jun 4 19:54:40 2018 -0700 ---------------------------------------------------------------------- .../apache/metamodel/AbstractDataContext.java | 2 + .../org/apache/metamodel/BatchUpdateScript.java | 3 ++ .../java/org/apache/metamodel/DataContext.java | 2 + .../metamodel/QueryPostprocessDataContext.java | 2 + .../java/org/apache/metamodel/UpdateScript.java | 3 ++ .../apache/metamodel/UpdateableDataContext.java | 3 ++ .../annotations/InterfaceStability.java | 56 ++++++++++++++++++++ .../java/org/apache/metamodel/query/Query.java | 2 + .../org/apache/metamodel/schema/Column.java | 3 ++ .../org/apache/metamodel/schema/ColumnType.java | 2 + .../apache/metamodel/schema/Relationship.java | 3 ++ .../org/apache/metamodel/schema/Schema.java | 2 + .../java/org/apache/metamodel/schema/Table.java | 3 ++ .../metamodel/kafka/KafkaDataContext.java | 2 + 14 files changed, 88 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/AbstractDataContext.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/AbstractDataContext.java b/core/src/main/java/org/apache/metamodel/AbstractDataContext.java index c098167..c1ff8e3 100644 --- a/core/src/main/java/org/apache/metamodel/AbstractDataContext.java +++ b/core/src/main/java/org/apache/metamodel/AbstractDataContext.java @@ -24,6 +24,7 @@ import java.util.List; import java.util.concurrent.ConcurrentHashMap; import java.util.concurrent.ConcurrentMap; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.data.DataSet; import org.apache.metamodel.query.CompiledQuery; import org.apache.metamodel.query.DefaultCompiledQuery; @@ -40,6 +41,7 @@ import org.apache.metamodel.schema.TableType; * Abstract implementation of the DataContext interface. Provides convenient implementations of all trivial and * datastore-independent methods. */ +@InterfaceStability.Evolving public abstract class AbstractDataContext implements DataContext { private static final String NULL_SCHEMA_NAME_TOKEN = "<metamodel.schema.name.null>"; http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/BatchUpdateScript.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/BatchUpdateScript.java b/core/src/main/java/org/apache/metamodel/BatchUpdateScript.java index 1f8a97f..e911dcf 100644 --- a/core/src/main/java/org/apache/metamodel/BatchUpdateScript.java +++ b/core/src/main/java/org/apache/metamodel/BatchUpdateScript.java @@ -18,12 +18,15 @@ */ package org.apache.metamodel; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Indicator sub-interface of {@link UpdateScript}. Implementing your updates * using this interface indicates to the underlying * {@link UpdateableDataContext} that the update script represents a large batch * update and that appropriate optimizations may be taken into use if available. */ +@InterfaceStability.Stable public interface BatchUpdateScript extends UpdateScript { } \ No newline at end of file http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/DataContext.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/DataContext.java b/core/src/main/java/org/apache/metamodel/DataContext.java index 38223b9..f91204b 100644 --- a/core/src/main/java/org/apache/metamodel/DataContext.java +++ b/core/src/main/java/org/apache/metamodel/DataContext.java @@ -20,6 +20,7 @@ package org.apache.metamodel; import java.util.List; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.data.DataSet; import org.apache.metamodel.query.CompiledQuery; import org.apache.metamodel.query.Query; @@ -34,6 +35,7 @@ import org.apache.metamodel.schema.Table; * datastores. The DataContext contains of the structure of data (in the form of * schemas) and interactions (in the form of queries) with data. */ +@InterfaceStability.Stable public interface DataContext { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/QueryPostprocessDataContext.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/QueryPostprocessDataContext.java b/core/src/main/java/org/apache/metamodel/QueryPostprocessDataContext.java index d6e287d..a873a32 100644 --- a/core/src/main/java/org/apache/metamodel/QueryPostprocessDataContext.java +++ b/core/src/main/java/org/apache/metamodel/QueryPostprocessDataContext.java @@ -27,6 +27,7 @@ import java.util.List; import java.util.Map; import java.util.stream.Collectors; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.convert.ConvertedDataSetInterceptor; import org.apache.metamodel.convert.Converters; import org.apache.metamodel.convert.HasReadTypeConverters; @@ -70,6 +71,7 @@ import org.slf4j.LoggerFactory; * Instead this superclass only requires that a subclass can materialize a single table at a time. Then the query will * be executed by post processing the datasets client-side. */ +@InterfaceStability.Evolving public abstract class QueryPostprocessDataContext extends AbstractDataContext implements HasReadTypeConverters { private static final Logger logger = LoggerFactory.getLogger(QueryPostprocessDataContext.class); http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/UpdateScript.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/UpdateScript.java b/core/src/main/java/org/apache/metamodel/UpdateScript.java index bc344ff..84bc666 100644 --- a/core/src/main/java/org/apache/metamodel/UpdateScript.java +++ b/core/src/main/java/org/apache/metamodel/UpdateScript.java @@ -18,6 +18,8 @@ */ package org.apache.metamodel; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Represents any updating operation or update script that can be executed on a * {@link UpdateableDataContext}. Users of MetaModel should implement their own @@ -26,6 +28,7 @@ package org.apache.metamodel; * execution. */ @FunctionalInterface +@InterfaceStability.Stable public interface UpdateScript { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/UpdateableDataContext.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/UpdateableDataContext.java b/core/src/main/java/org/apache/metamodel/UpdateableDataContext.java index 6c369ea..93f5d6e 100644 --- a/core/src/main/java/org/apache/metamodel/UpdateableDataContext.java +++ b/core/src/main/java/org/apache/metamodel/UpdateableDataContext.java @@ -18,9 +18,12 @@ */ package org.apache.metamodel; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Represents a {@link DataContext} that supports updating write-operations. */ +@InterfaceStability.Stable public interface UpdateableDataContext extends DataContext { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/annotations/InterfaceStability.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/annotations/InterfaceStability.java b/core/src/main/java/org/apache/metamodel/annotations/InterfaceStability.java new file mode 100644 index 0000000..ee1b656 --- /dev/null +++ b/core/src/main/java/org/apache/metamodel/annotations/InterfaceStability.java @@ -0,0 +1,56 @@ +/** + * 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.metamodel.annotations; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * 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 Stable}, {@link Evolving} or {@link Unstable}. + */ +@InterfaceStability.Evolving +public class InterfaceStability { + + /** + * Compatibility is maintained in minor and patch releases. Compatibility may only be broken in a major release + * (i.e. 0.m), and usually only for APIs that have been deprecated for at least one major/minor release cycle. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Stable { + } + + /** + * Compatibility may be broken at minor release (i.e. m.x). + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Evolving { + } + + /** + * No guarantee is provided as to reliability, availability or stability across any level of release granularity. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Unstable { + } +} http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/query/Query.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/query/Query.java b/core/src/main/java/org/apache/metamodel/query/Query.java index e29b7dd..bcf1613 100644 --- a/core/src/main/java/org/apache/metamodel/query/Query.java +++ b/core/src/main/java/org/apache/metamodel/query/Query.java @@ -24,6 +24,7 @@ import java.util.List; import org.apache.metamodel.DataContext; import org.apache.metamodel.MetaModelException; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.query.OrderByItem.Direction; import org.apache.metamodel.query.parser.QueryParserException; import org.apache.metamodel.query.parser.QueryPartCollectionProcessor; @@ -64,6 +65,7 @@ import org.apache.metamodel.util.NumberComparator; * * @see DataContext */ +@InterfaceStability.Stable public final class Query extends BaseObject implements Cloneable, Serializable { private static final long serialVersionUID = -5976325207498574216L; http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/schema/Column.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/schema/Column.java b/core/src/main/java/org/apache/metamodel/schema/Column.java index 368b338..6874990 100644 --- a/core/src/main/java/org/apache/metamodel/schema/Column.java +++ b/core/src/main/java/org/apache/metamodel/schema/Column.java @@ -20,12 +20,15 @@ package org.apache.metamodel.schema; import java.io.Serializable; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Represents a column and it's metadata description. Columns reside within a * Table and can be used as keys for relationships between tables. * * @see Table */ +@InterfaceStability.Stable public interface Column extends Comparable<Column>, Serializable, NamedStructure { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/schema/ColumnType.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/schema/ColumnType.java b/core/src/main/java/org/apache/metamodel/schema/ColumnType.java index 8c56763..589e88b 100644 --- a/core/src/main/java/org/apache/metamodel/schema/ColumnType.java +++ b/core/src/main/java/org/apache/metamodel/schema/ColumnType.java @@ -37,11 +37,13 @@ import java.util.Map; import java.util.Set; import java.util.UUID; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.util.HasName; /** * Represents the data-type of columns. */ +@InterfaceStability.Stable public interface ColumnType extends HasName, Serializable { /* http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/schema/Relationship.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/schema/Relationship.java b/core/src/main/java/org/apache/metamodel/schema/Relationship.java index 12a5c8c..b91bad2 100644 --- a/core/src/main/java/org/apache/metamodel/schema/Relationship.java +++ b/core/src/main/java/org/apache/metamodel/schema/Relationship.java @@ -21,6 +21,8 @@ package org.apache.metamodel.schema; import java.io.Serializable; import java.util.List; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Represents a relationship between two tables where one set of columns is the * primary key, and another set is the foreign key. @@ -28,6 +30,7 @@ import java.util.List; * @see Table * @see Column */ +@InterfaceStability.Stable public interface Relationship extends Serializable, Comparable<Relationship> { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/schema/Schema.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/schema/Schema.java b/core/src/main/java/org/apache/metamodel/schema/Schema.java index 082acb1..ddc3336 100644 --- a/core/src/main/java/org/apache/metamodel/schema/Schema.java +++ b/core/src/main/java/org/apache/metamodel/schema/Schema.java @@ -23,6 +23,7 @@ import java.util.Collection; import java.util.List; import org.apache.metamodel.DataContext; +import org.apache.metamodel.annotations.InterfaceStability; /** * Represents a schema and it's metadata description. Schemas represent a @@ -31,6 +32,7 @@ import org.apache.metamodel.DataContext; * @see DataContext * @see Table */ +@InterfaceStability.Stable public interface Schema extends Comparable<Schema>, Serializable, NamedStructure { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/core/src/main/java/org/apache/metamodel/schema/Table.java ---------------------------------------------------------------------- diff --git a/core/src/main/java/org/apache/metamodel/schema/Table.java b/core/src/main/java/org/apache/metamodel/schema/Table.java index d549dba..5e92d4b 100644 --- a/core/src/main/java/org/apache/metamodel/schema/Table.java +++ b/core/src/main/java/org/apache/metamodel/schema/Table.java @@ -22,6 +22,8 @@ import java.io.Serializable; import java.util.Collection; import java.util.List; +import org.apache.metamodel.annotations.InterfaceStability; + /** * Represents a table and it's metadata description. Tables reside within a * schema and contains columns and relationships to other tables. @@ -29,6 +31,7 @@ import java.util.List; * @see Schema * @see Column */ +@InterfaceStability.Stable public interface Table extends Comparable<Table>, Serializable, NamedStructure { /** http://git-wip-us.apache.org/repos/asf/metamodel/blob/b5291990/kafka/src/main/java/org/apache/metamodel/kafka/KafkaDataContext.java ---------------------------------------------------------------------- diff --git a/kafka/src/main/java/org/apache/metamodel/kafka/KafkaDataContext.java b/kafka/src/main/java/org/apache/metamodel/kafka/KafkaDataContext.java index 8f4d7a7..a4dea28 100644 --- a/kafka/src/main/java/org/apache/metamodel/kafka/KafkaDataContext.java +++ b/kafka/src/main/java/org/apache/metamodel/kafka/KafkaDataContext.java @@ -36,6 +36,7 @@ import org.apache.metamodel.QueryPostprocessDataContext; import org.apache.metamodel.UpdateScript; import org.apache.metamodel.UpdateSummary; import org.apache.metamodel.UpdateableDataContext; +import org.apache.metamodel.annotations.InterfaceStability; import org.apache.metamodel.data.DataSet; import org.apache.metamodel.data.FirstRowDataSet; import org.apache.metamodel.data.MaxRowsDataSet; @@ -51,6 +52,7 @@ import org.apache.metamodel.schema.MutableTable; import org.apache.metamodel.schema.Schema; import org.apache.metamodel.schema.Table; +@InterfaceStability.Unstable public class KafkaDataContext<K, V> extends QueryPostprocessDataContext implements UpdateableDataContext { public static final String SYSTEM_PROPERTY_CONSUMER_POLL_TIMEOUT = "metamodel.kafka.consumer.poll.timeout";
